覆蓋層與回饋
錨定提示
錨定在元素旁的 React 提示元件：hover 或鍵盤聚焦延遲開啟，同群組內快速移動時立即切換，淡入微縮放並在視窗邊緣自動翻轉，附指向觸發元素的箭頭。
替 icon 按鈕、縮寫或任何需要補充說明的元素加上一行提示。滑鼠停留超過延遲（預設 700ms）才開啟，鍵盤 Tab 聚焦時立即開啟；包在 Tooltip.Provider 裡的一組提示共享計時——沿著工具列掃過時，下一個提示不再等待延遲、直接切換。浮層以 portal 掛到 body、position: fixed 定位，空間不足時翻到對側並在交叉軸上平移留在視窗內，箭頭始終指向觸發元素中心。觸控裝置改為長按開啟。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add tooltipPlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
700
100
編輯中的呼叫預設屬性
<Tooltip/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/tooltip.json或在 components.json 設定 registries 後，改用 @webberui/tooltip 安裝。
使用
import { Tooltip } from "@/components/ui/tooltip";
// 單一提示
<Tooltip content="複製連結">
<button type="button" aria-label="複製連結">…</button>
</Tooltip>
// 工具列：同一個 Provider 下快速切換時立即顯示
<Tooltip.Provider delay={700} skipDelay={300}>
<Tooltip content="粗體 ⌘B">
<button type="button" aria-label="粗體">B</button>
</Tooltip>
<Tooltip content="斜體 ⌘I" side="bottom">
<button type="button" aria-label="斜體">I</button>
</Tooltip>
</Tooltip.Provider>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
content | ReactNode | — | 提示內容 |
children | ReactElement | — | 單一可聚焦的觸發元素；事件、ref 與 aria-describedby 會以 cloneElement 合併進去 |
side | "top" | "right" | "bottom" | "left" | "top" | 偏好方向；空間不足時自動翻到對側 |
align | "start" | "center" | "end" | "center" | 交叉軸對齊 |
sideOffset | number | 4 | 與觸發元素的距離（px） |
alignOffset | number | 0 | 交叉軸位移（px） |
collisionPadding | number | 8 | 與視窗邊緣保持的最小距離（px） |
delay | number | 700 | 開啟延遲（ms）；未指定時沿用 Tooltip.Provider 的 delay |
closeDelay | number | 0 | 滑鼠離開後的關閉延遲（ms） |
duration | number | 100 | 進出場動畫時長（ms），同時寫入 --wb-tooltip-duration |
open | boolean | — | 受控開關狀態 |
defaultOpen | boolean | false | 非受控模式的初始開關狀態 |
onOpenChange | (open: boolean) => void | — | 開關狀態改變時回呼 |
disabled | boolean | false | 停用：不開啟，已開啟的也會關閉 |
showArrow | boolean | true | 是否顯示指向觸發元素的箭頭 |
className | string | — | 併入浮層根元素（深色提示泡泡本身） |
Tooltip.Provider
| 欄位 | 型別 | 預設值 | 說明 |
|---|---|---|---|
delay | number | 700 | 群組內提示的預設開啟延遲（ms） |
skipDelay | number | 300 | 任一提示關閉後這段時間內（ms）移到同群組的另一個觸發元素，立即開啟、不等延遲 |
children | ReactNode | — | 群組內容 |
細節
- 開關規則：滑鼠移入啟動延遲計時、移出取消或依
closeDelay關閉；滑鼠按下觸發元素時提示收起；鍵盤聚焦（:focus-visible）立即開啟、失焦關閉；按 Escape 關閉；觸發元素所在的捲動容器捲動時關閉。 - 觸控：長按 500ms 開啟，手指離開 1500ms 後關閉；長按後的那一次 click 會被吃掉，不會誤觸按鈕。
- 定位：首次量測完成前浮層為
visibility: hidden，不會在左上角閃一下；觸發元素或提示尺寸改變、視窗縮放與任何容器捲動都會以 rAF 節流重算。浮層帶有data-side／data-align（翻轉後的實際落點），可用來寫自訂樣式。 - 動畫：淡入、由 0.95 縮放到 1，並從觸發元素那一側滑出 8px；
transform-origin依實際落點設定，縮放從貼近觸發元素的那一角長出來。要全域調整節奏，可在 CSS 覆寫--wb-tooltip-duration。 - 提示本身是
pointer-events: none，不可互動；需要放連結或按鈕的內容請改用 Popover 類元件。
可及性
- 浮層為
role="tooltip"，id由useId產生；開啟時觸發元素加上aria-describedby指向它（保留原本的aria-describedby） - 鍵盤 Tab 聚焦即開啟，Escape 關閉；滑鼠點擊造成的聚焦不會開啟，避免提示黏著不走
- 只有 icon 的觸發按鈕仍應自帶
aria-label——提示是補充說明，不取代可及名稱 - 使用者系統開啟「減少動態效果」時，只保留淡入淡出（時長不變），不縮放、不位移