Cursor Tip

👑Pioneer

CursorTip is a specialized tooltip component that is not fixed to a specific DOM element; instead, it tracks the movement of the mouse cursor in real-time. It combines the lightweight nature of Poptip with the rich content capabilities of Popinfo, allowing it to display simple text, titles, and semantic colors.

This component is commonly used in scenarios where users need to view statuses or attributes in real-time or engage in exploratory interactions.

Basic Usage

Component Call

Wrap the <TuiCursorTip> around the trigger area. When the mouse moves within this area, the tooltip will follow the cursor.

<template>
  <div class="demo-box">
    <TuiCursorTip content="Text following the mouse movement">
      <div class="hover-area">Move here</div>
    </TuiCursorTip>

    <TuiCursorTip 
      title="Detailed Information" 
      content="Showing more specific description content here..."
    >
      <div class="hover-area">View Details</div>
    </TuiCursorTip>
  </div>
</template>

Directive Call (v-tui-cursor-tip)

Use the directive to conveniently add a cursor tip to an element.

<template>
  <div 
    v-tui-cursor-tip="{ 
      title: 'Directive Tip', 
      content: 'Generated via v-tui-cursor-tip', 
      placement: 'top-end' 
    }" 
    class="hover-area"
  >
    Directive Trigger Area
  </div>
</template>

Visual Style

Consistent with the Popover series components, it supports rich semantic colors, tone configurations, and frosted glass effects.

<template>
  <div class="row">
    <TuiCursorTip 
      content="Deletions cannot be recovered" 
      title="Warning" 
      type="danger" 
    >
      <TuiButton type="danger">Danger Zone</TuiButton>
    </TuiCursorTip>

    <TuiCursorTip 
      content="Background blur effect" 
      :transparent="true" 
      :backgroundBlur="true" 
      tone="weak"
    >
      <div class="glass-area">Glass Effect</div>
    </TuiCursorTip>
  </div>
</template>

Geometric Configuration

Because the tooltip is positioned closely to the mouse, you can fine-tune the distance between the cursor and the tip using caretSize and caretOffset to avoid obstructing the user's view or focus.

• caretSize: Controls the size of the tooltip's arrow.
• caretOffset: Controls the offset distance of the tooltip relative to the mouse cursor.

<template>
  <TuiCursorTip 
    content="A bit further from the cursor" 
    :caretSize="8" 
    :caretOffset="10"
  >
    <div class="area">Large Offset</div>
  </TuiCursorTip>
</template>

Global Interaction Monitoring

To provide a smooth experience, CursorTip integrates global interaction services:

• ESC Response (escCounter): When the user presses the Esc key, the current cursor tip will be forcibly hidden, even if the mouse remains within the trigger area. It will stay hidden until the mouse leaves and re-enters the area.
• Note: Unlike standard Poptips, cursor tips do not support "click to close" or "click outside to close" logic, as their lifecycle depends entirely on the mouse hover state.

API Reference

Props

The following configuration items are filtered for cursor tips.

Property	Description	Type	Default
content	Tip content	String	—
title	Title text (optional)	String	—
placement	Orientation relative to the cursor (e.g., top-start, bottom-end)	String	'bottom-end'
type	Semantic type (primary, success, danger, warning, etc.)	String	null
tone	Tone intensity (base, weak, strong, strongInvert)	String	'base'
caretSize	Arrow size (px)	Number	5
caretOffset	Offset distance from the cursor (px)	Number	2
delay	Display delay (ms)	Number	100
transparent	Whether to enable background semi-transparency	Boolean	true
backgroundBlur	Whether to enable background blur	Boolean	true
disabled	Whether to disable	Boolean	false
zIndex	Z-index	Number	2000

Directives

Directive Name	Description	Parameter
v-tui-cursor-tip	Binds the cursor tip configuration object	Object (Prop configuration)

Positioning Core: Floating UI

The positioning mechanism of CursorTip is also based on Floating UI, utilizing a special Virtual Element technique.

The component captures mouse MouseEvent coordinates in real-time and converts them into a virtual element (Virtual Element) with zero width and height to serve as the anchor for Floating UI. This allows the tooltip to "snap" to the moving cursor just as it would to a DOM element, while retaining Floating UI's powerful Flip and Shift capabilities. When the cursor nears the edge of the screen, the tooltip automatically adjusts its direction to ensure the content remains within the visible viewport.