Cursor Tooltip
跟隨游標的彈性提示框，以彈簧追隨座標並在邊緣自動翻邊，支援鍵盤聚焦錨定。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
14
0
<CursorTooltip />
安裝
npx shadcn@latest add https://webberui.com/r/cursor-tooltip.json或在 components.json 設定 registries 後，改用 @webberui/cursor-tooltip 安裝。
安裝依賴後，從 registry JSON（/r/cursor-tooltip.json 的 files[0].content）複製 cursor-tooltip.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge使用
import { CursorTooltip } from "@/components/ui/cursor-tooltip";
<CursorTooltip content="拖曳可重新排序">
<button>Hover me</button>
</CursorTooltip>提示框以 portal 渲染到 document.body，跟隨游標移動；content 可傳入任意節點，做出帶圖示的富提示：
<CursorTooltip
variant="smooth"
content={
<span className="flex items-center gap-1.5">
<Sparkles className="size-3.5" /> 已完成
</span>
}
>
<StatusDot />
</CursorTooltip>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
children | React.ReactNode | — | 觸發區域，游標移入或鍵盤聚焦時顯示提示 |
content | React.ReactNode | — | 提示框內容，可為文字或任意節點 |
variant | "spring" | "smooth" | "instant" | "spring" | 跟隨手感：彈性回彈／緊致跟手／零延遲緊貼 |
offset | number | { x: number; y: number } | 14 | 提示框相對游標的偏移（px） |
openDelay | number | 0 | 顯示前的延遲（毫秒） |
disabled | boolean | false | 停用提示：觸發區照常渲染，但不顯示提示 |
className | string | — | 追加到提示框氣泡的 class |
wrapperClassName | string | — | 追加到觸發區包裹層的 class |
細節
- 座標透過
useMotionValue直接寫入，mousemove不觸發 React re-render；useSpring讓提示框以彈簧追隨游標，低阻尼即產生「彈性」回彈感。 spring帶明顯回彈、smooth緊致幾乎不過衝、instant直接綁定原始座標零延遲緊貼。- 首次顯示時彈簧會
jump到游標定位，不會從畫面角落飛入。 - 提示框接近視口右／下緣時自動翻到游標另一側，並夾在邊界內，不會被裁切或遮住游標。
可及性
- 觸發區以
onFocus/onBlur支援鍵盤：聚焦時提示框錨定在觸發區正上方（空間不足則落到下方），而非游標位置。 - 單一子元素時
aria-describedby會掛到子元素本身，輔助科技聚焦時朗讀提示內容；提示框帶role="tooltip"。 - 按下
Esc立即關閉提示框。 - 使用者系統開啟「減少動態效果」時，停用彈簧與縮放，退化為緊貼游標的純淡入淡出。
- 提示框為
pointer-events-none，永遠不攔截游標事件。