Tooltip
Mẫu chuẩnMột nhãn nổi ngắn giải thích thêm cho một control đã có tên. Mở bằng hover hoặc bằng tiêu điểm bàn phím — không phải chỉ hover.
Playground
TooltipContent portal ra document.body, nằm ngoài KitBrandScope, nên panel theo theme của trang, không theo brand đang chọn.
Dùng Tab để đưa tiêu điểm vào nút Lưu — tooltip mở bằng tiêu điểm chứ không chỉ bằng hover. Escape đóng.
import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@nexobox/ui";
<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<Button type="button">Lưu</Button>
</TooltipTrigger>
<TooltipContent side="top" align="center">Lưu (Ctrl+S)</TooltipContent>
</Tooltip>
</TooltipProvider>Khi nào sử dụng
Nên dùng
Một nhãn ngắn bổ sung cho một control đã có tên: phím tắt của một hành động, đơn vị của một trường số, tên đầy đủ của một nút chỉ có icon — khi nút vẫn có aria-label riêng.
Tránh dùng
Thông tin người dùng cần để hoàn thành việc — tooltip biến mất khi rời hover/focus và không đến được trên thiết bị cảm ứng. Tên truy cập của một nút chỉ có icon. Nội dung tương tác (link, nút, form) — đó là Popover. Nhãn nổi phong phú hơn (ảnh, nhiều đoạn, hành động phụ) — đó là HoverCard, chưa có trong bộ kit này.
Anatomy
| # | Phần | Ghi chú |
|---|---|---|
| 1 | Provider | Bọc ngoài toàn trang hoặc một vùng; giữ delayDuration và skipDelayDuration dùng chung cho mọi Tooltip con. |
| 2 | Root | Tooltip, quản lý state mở/đóng theo hover và focus. |
| 3 | Trigger | Phần tử phải nhận được tiêu điểm — dùng asChild bọc Button hoặc <a>. |
| 4 | Content | Portal ra document.body, lớp --nf-foundation-layer-tooltip. |
Không có Arrow. Bộ kit không có token mũi tên — cùng quyết định đã ghi ở Popover. Radix phát data-state là delayed-open (mở sau delayDuration) hoặc instant-open (chuyển nhanh giữa hai trigger trong skipDelayDuration) — không phát open như Popover.
Variants
Không có variant, không có size, không có arrow. Loading, error, empty: không có — Tooltip không bất đồng bộ.
Hover hoặc Tab vào nút để xem tooltip neo phía trên.
Hover hoặc Tab vào nút để xem tooltip neo bên phải.
Hover hoặc Tab vào nút để xem tooltip neo phía dưới.
Hover hoặc Tab vào nút để xem tooltip neo bên trái.
Design tokens
Content đọc --nf-semantic-inverse-surface, --nf-semantic-inverse-text-primary, --nf-foundation-layer-tooltip, --nf-foundation-radius-small, --nf-component-overlay-shadow, --nf-foundation-space-1, --nf-foundation-space-2, --nf-foundation-layout-sidebar, --nf-motion-popover-in, --nf-motion-popover-out, và năm thuộc tính --nf-foundation-typography-caption-* (font-family, font-size, font-weight, letter-spacing, line-height). Không có token --nf-component-tooltip-*.
API & triển khai
| Prop | Mặc định | Quy ước |
|---|---|---|
| delayDuration (Provider) | 700 | Số ms hover trước khi mở; áp cho mọi Tooltip con. |
| skipDelayDuration (Provider) | 300 | Cửa sổ chuyển sang Tooltip khác không chờ delay lại. |
| open / defaultOpen (Root) | — | Chế độ controlled / uncontrolled. |
| onOpenChange (Root) | — | Phát khi trạng thái đổi. |
| asChild (Trigger) | false | Bọc trigger thật, bắt buộc phần tử đó nhận được tiêu điểm. |
| side (Content) | "top" | Cạnh neo. |
| sideOffset (Content) | 8 | Khoảng cách tới trigger; primitive đặt mặc định 8. |
| align (Content) | "center" |
TooltipContentProps = ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> — mọi thuộc tính Radix Content gốc đều nhận, kể cả các prop không liệt kê ở trên.