Tooltip
A small inverse label that names a control. It opens on hover and keyboard focus. There is no Tooltip component: the look is written twice, once inside IconButton and once in the web app's chip tooltip, which says it is copied because the design system does not export it.
The look
The text colour as the fill and the page colour as the text, 14/21 at weight 500, 10px by 6px padding, 8px corners, 8px above its trigger. Hover a button, or Tab to it.
TSX
<TooltipProvider>
<IconButton label="Upload a file" hint="Add a message first" variant="control" disabled>
<UploadIcon />
</IconButton>
<IconButton label="Site language: English" variant="control">
<GlobeIcon />
</IconButton>
<IconButton label="Where it happened: Choose your state" variant="control">
<PinIcon />
</IconButton>
</TooltipProvider>On this page
These tooltips are plain HTML and CSS, so they ship no React. They open the way the real one does: after a mouse rests on the button for 600ms, or at once on keyboard focus, and they close on Escape. The real one also flips below the button when there is no room above, which these do not.
Two copies
IconButton draws this tooltip inside itself. The web app's chip draws the same look separately, in its own tooltip content, and its comment says it is copied because the design system does not export a Tooltip. The two differ only in reduced motion.
Code
TSX
<TooltipProvider>
<IconButton label="Upload a file" hint="Add a message first" variant="control" disabled>
<UploadIcon />
</IconButton>
</TooltipProvider>
{/* the chip's copy, inside a Tooltip.Root beside the trigger */}
<ChipTooltipContent>{accessibleName}</ChipTooltipContent>The first part is from icon-button.stories.tsx, trimmed; the second is from location-chip.tsx and language-menu.tsx. The chip's copy is switched off while the chip shows its full label.
Variants
| Prop | Value | How it looks |
|---|---|---|
| popup | fill and text | The inverse of the page: the text colour fills it (#00172E light, #FAFDFF dark) and the page colour is the text (#FAFDFF light, #00172E dark). Text is 14/21 (text-sm) at weight 500. |
| popup | box | 10px side and 6px top and bottom padding, an 8px radius (plain, not a squircle). No border, no shadow and no arrow. It takes its text's width. |
| popup | position | Above the trigger, centred, 8px away. The library's own defaults are not changed: it flips below when there is no room above, and keeps 5px from the window edge. |
| popup | motion | Fades over 150ms, opacity only, at Tailwind's default easing. It starts and ends at 0. |
| open delay | 600ms | The library's default for a hover, and the mouse only. Keyboard focus opens it at once. Close delay is 0. No delay is written in the repository. |
| copy | IconButton | Has no reduced-motion rule, so under reduced motion it still fades. |
| copy | web chip | The same classes plus motion-reduce:transition-none, so under reduced motion it appears at once. That is the only difference between the copies. |
States
| State | How it looks |
|---|---|
| hidden | Not in the page until its trigger is hovered or focused. |
| shown | Opens after the delay on a mouse hover, and at once on keyboard focus. Closes on leave, blur or Escape. |
| in a provider | Inside a TooltipProvider, a tooltip that opens within 400ms of another one closing skips the delay and the fade. |
| disabled trigger | An IconButton that is disabled stays focusable, so its tooltip can show the hint. |
| chip tooltip off | While a chip shows its full label there is no tooltip. At the short or icon stage it shows the chip's accessible name. |
| stacking | not written: neither copy sets a z-index |
| hover, pressed, focus | not written for the popup itself |
Props
Import from @repo/ui/icon-button.
| Prop | Type | Default | What it does |
|---|---|---|---|
| label | string | default required | The accessible name and the tooltip text. |
| hint | string | undefined | Tooltip text when it differs from the name, such as why a button is disabled. | |
| tooltip | boolean | default true | false draws no tooltip. |
| TooltipProvider | Tooltip.Provider | Wraps a region so its tooltips share one open delay. The hero does. | |
| ChipTooltipContent | ReactNode children | The web app's copy. It goes inside a Tooltip.Root, beside a Tooltip.Trigger. |
Use it well
A tooltip names a control. Never put in one what a person needs to read: touch has no hover.
Wrap the region in TooltipProvider so its tooltips share one open delay.
Give a disabled button a hint that says why. It stays focusable so the hint can show.
If the design system exports a Tooltip, the web chip's copy should move onto it, as chip-tooltip.tsx says.