Fair Case

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.

Add a message first
A hint, on a disabled button
Site language: English
The label, as the name
Where it happened: Choose your state
A longer name

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

Variants
PropValueHow it looks
popupfill and textThe 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.
popupbox10px 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.
popuppositionAbove 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.
popupmotionFades over 150ms, opacity only, at Tailwind's default easing. It starts and ends at 0.
open delay600msThe 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.
copyIconButtonHas no reduced-motion rule, so under reduced motion it still fades.
copyweb chipThe same classes plus motion-reduce:transition-none, so under reduced motion it appears at once. That is the only difference between the copies.

States

States
StateHow it looks
hiddenNot in the page until its trigger is hovered or focused.
shownOpens after the delay on a mouse hover, and at once on keyboard focus. Closes on leave, blur or Escape.
in a providerInside a TooltipProvider, a tooltip that opens within 400ms of another one closing skips the delay and the fade.
disabled triggerAn IconButton that is disabled stays focusable, so its tooltip can show the hint.
chip tooltip offWhile a chip shows its full label there is no tooltip. At the short or icon stage it shows the chip's accessible name.
stackingnot written: neither copy sets a z-index
hover, pressed, focusnot written for the popup itself

Props

Import from @repo/ui/icon-button.

Props
PropTypeDefaultWhat it does
labelstringdefault requiredThe accessible name and the tooltip text.
hintstring | undefinedTooltip text when it differs from the name, such as why a button is disabled.
tooltipbooleandefault truefalse draws no tooltip.
TooltipProviderTooltip.ProviderWraps a region so its tooltips share one open delay. The hero does.
ChipTooltipContentReactNode childrenThe 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.