Compact and detailed labels on hover, focus, or a viewport point.
Also known as: hover tip, focus tip, hover label, info tip
Install with the CLI, or copy the component source into your project.
Add tooltip (npm)
1npx --yes -p @default-file/ui df-ui add tooltip
Compact tip for short hints kept on one-line.
Detailed panel with copy kept on one-line and truncated with an ellipsis.
Detailed panel with wrap enabled so longer copy flows across multiple lines.
Compare light, dark, and inverse. inverse uses a dark tip on light pages and a light tip on dark pages.
Hide the pointer by setting arrow to false.
Anchor a controlled tip to a viewport point with no trigger. Auto-hides using --df-duration-tip-hold.
Corner placements (top left, top right, bottom left, bottom right) plus centred top, right, bottom, and left.
Compact or detailed labels on hover, focus, or a viewport point. Compose Tooltip, TooltipTrigger, and TooltipContent. Point mode uses anchorPoint and omits TooltipTrigger.
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | "compact" | "detailed" | "compact" | Content density and typography. |
| appearance | "light" | "dark" | "inverse" | "inverse" | Panel surface color. inverse uses a dark tip on light pages and a light tip on dark pages; light and dark lock one surface. |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | - | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when open state changes. |
| delayDuration | number | 200 | Hover delay in milliseconds before showing. |
| anchorPoint | { x: number; y: number } | null | - | Viewport point to anchor the tip when there is no trigger. Use with controlled open. |
| dismissDuration | number | - | Auto-hide duration in milliseconds while open. When omitted in point mode, uses --df-duration-tip-hold. |
| Prop | Type | Default | Notes |
|---|---|---|---|
| render | ReactElement | - | Host element to attach tooltip behavior to. |
| children | ReactNode | - | Trigger content when not using render. |
| Prop | Type | Default | Notes |
|---|---|---|---|
| side | "top" | "bottom" | "left" | "right" | "top" | Preferred placement side. Flips when there is not enough space. |
| align | "start" | "center" | "end" | "center" | Alignment along the side. |
| sideOffset | number | 14 | Gap between trigger and content. |
| alignOffset | number | 0 | Shift along the alignment axis. |
| wrap | boolean | - | For the detailed variant, wrap text within the max width. |
| arrow | boolean | true | Show the pointing caret. The anchoring engine keeps it aimed at the trigger or anchor point after collision clamping. |
| children | ReactNode | - | Tooltip label or detailed body. |
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-tooltip-max-width | CSS length | 16rem | Compact variant max width. |
| --df-tooltip-max-width-detailed | CSS length | 18rem | Detailed variant max width. |
| --df-tooltip-arrow-offset | CSS length | 3.5px | Arrow distance from the content edge. |
| --df-tooltip-arrow-align-nudge | CSS length | 4px | Half-caret optical nudge for the trigger-tracked caret. |
| --df-anchor-arrow-cross | CSS length | 50% | Trigger-centered caret offset on the cross axis. Set by the anchoring engine after collision clamping. |
| --df-anchor-arrow-cross-inset | CSS length | calc(3 * var(--spacing-unit)) | Minimum inset that keeps the trigger-tracked caret on the panel edge. |
| --df-duration-tip-hold | CSS time | 1800ms | Default auto-hide duration for point-anchored tips. |
| --df-shadow-tooltip | CSS shadow | drop-shadow(0 4px 6px rgb(0 0 0 / 0.1)) drop-shadow(0 2px 3px rgb(0 0 0 / 0.08)) | Drop shadow that includes the arrow silhouette. |
| --popover | CSS color | var(--df-neutral-900) | Tip fill. Remapped by appearance (inverse, light, or dark). |
| --popover-foreground | CSS color | var(--df-neutral-0) | Tip text color. Remapped by appearance. |
| --foreground | CSS color | var(--df-neutral-0) | Used for the tip border mix. Remapped by appearance. |