Component
Tooltip
Gợi ý chữ ngắn cho phần tử nó bọc, hiện khi hover và khi focus bằng bàn phím. Surface inverse, ngược với mode hiện tại (light trong dark mode, dark trong light mode), với bóng medium và chữ 14px. Chỉ chữ: mọi thứ người dùng tác động thuộc về popover hoặc dialog.
Xem trước
import { IconLink } from "@tabler/icons-react"
import { Button } from "@/components/ui/button"
import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="Copy liên kết">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>Cách dùng
Khi nào dùng
- Nêu icon button làm gì cho người dùng nhìn được, cùng từ với aria-label của nó.
- Hiện một chi tiết một số người dùng muốn nhưng không ai cần, chẳng hạn ngày đầy đủ sau 2 giờ trước.
Khi nào không dùng
- Mọi thứ người dùng phải đọc để xong một việc. Viết trên trang, hoặc trong description của một Field.
- Link, button hoặc control khác bên trong gợi ý. Dùng Dialog cho mọi thứ người dùng tác động.
- Tên duy nhất của icon button. Cũng đặt aria-label cho button.
Biến thể
side
Phía của trigger mà tooltip mở. Nó lật khi không đủ chỗ.
import { IconLink } from "@tabler/icons-react"
import { Button } from "@/components/ui/button"
import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="Copy liên kết">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>
<Tooltip content="Copy liên kết" side="right">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>
<Tooltip content="Copy liên kết" side="bottom">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>
<Tooltip content="Copy liên kết" side="left">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>align
Căn dọc theo mép của trigger.
import { IconLink } from "@tabler/icons-react"
import { Button } from "@/components/ui/button"
import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="Copy liên kết" align="start">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>
<Tooltip content="Copy liên kết">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>
<Tooltip content="Copy liên kết" align="end">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>Ví dụ
Mặc định
import { IconLink } from "@tabler/icons-react"
import { Button } from "@/components/ui/button"
import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="Copy liên kết">
<Button variant="secondary" iconOnly aria-label="Copy liên kết">
<IconLink size={16} />
</Button>
</Tooltip>Chi tiết thêm
Ngày đầy đủ sau một ngày tương đối, cho số ít người dùng muốn xem.
import { Button } from "@/components/ui/button"
import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="6 tháng 10 năm 2026, 14:32" side="bottom">
<Button variant="ghost" size="sm">Đã sửa 2 giờ trước</Button>
</Tooltip>Nên và không nên
Nên
- Nêu icon button làm gì, cùng từ với aria-label của nó.
- Thêm một thông tin người dùng có thể muốn nhưng không cần: ngày đầy đủ sau một ngày tương đối, một phím tắt.
- Giữ trong vài từ trên một dòng.
- Bọc các tooltip nằm cạnh nhau, chẳng hạn các button của một toolbar, trong TooltipGroup: khi một tooltip đã hiện, tooltip tiếp theo mở ngay, không delay và không fade.
Không nên
- Đừng đặt link, button hoặc control khác trong tooltip.
- Đừng dùng tooltip làm tên duy nhất của icon button.
- Đừng đặt thứ người dùng cần để xong một việc chỉ trong tooltip.
- Đừng bọc phần tử không nhận focus, chẳng hạn chữ thuần hoặc button disabled.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| content bắt buộc | node | - | - | Gợi ý: vài từ chữ thuần, sentence case, không dấu chấm khi là cụm. Sao chép liên kết, Đã lưu trữ 3 ngày trước. |
| side | enum | top | right | bottom | left | top | Phía của trigger mà tooltip mở. Nó lật khi không đủ chỗ. |
| align | enum | start | center | end | center | Căn dọc theo mép của trigger. |
| sideOffset | number | - | 4 | Khoảng cách giữa trigger và tooltip, tính bằng px; 4 khớp spacing-xs. |
| delayDuration | number | - | 200 | Thời gian chờ, tính bằng ms, trước khi hover mở tooltip. Focus mở ngay. Trong TooltipGroup, delay của nhóm được dùng trừ khi prop này được đặt. |
| disabled | boolean | - | false | Render trigger mà không có tooltip. |
| open | boolean | - | - | Trạng thái mở controlled, cho một tour hoặc một test. Đi cùng onOpenChange. |
| defaultOpen | boolean | - | - | Mở ở lần render đầu, khi bạn không control nó. |
| onOpenChange | function | - | - | Được gọi với true hoặc false khi hover, focus hoặc Escape mở hoặc đóng tooltip. |
Slot
| Tên | Bắt buộc | Mô tả |
|---|---|---|
| trigger | có | Một phần tử nhận focus: một Button, một link. Tooltip mô tả phần tử đó. |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Tooltip: nền inverse (light trên trang dark, dark trên trang light) với chữ inverse, viền trong suốt (viền hiện ở mode forced-colors, mode này bỏ nền), radius-element, shadow-med, chữ 14px, rộng tối đa 320px. |
| trigger | Phần tử con mà tooltip mô tả. Nhận aria-describedby khi tooltip đang mở. |
Khả năng truy cập
Role: tooltip
| Phím | Hành động |
|---|---|
| Tab | Focus trên trigger mở tooltip ngay. |
| Escape | Đóng tooltip; focus ở lại trên trigger. |
- Trigger phải nhận focus (button hoặc link), để người dùng bàn phím cũng nhận gợi ý. Chữ tooltip được đọc như mô tả của trigger.
- Tooltip không bao giờ tự đặt tên icon button: button vẫn cần aria-label.
- Hover không có trên màn hình cảm ứng. Đừng đặt thứ người dùng cần chỉ trong tooltip.
- Tooltip giữ mở khi con trỏ di lên nó, để đọc được ở mọi mức zoom.
Cài đặt
npx werewolf-ui add tooltipChạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.