Tooltip
Preview appears after the next Storybook update.
<Tooltip />When to use
Use it for
- Every IconButton, with the same text as its label.
- Truncated text, to show the full value.
- Wrap the app once in TooltipProvider so neighbouring tooltips open instantly after the first one.
- Plain-script pages without React put tooltipAttributes() from @bridge-ds/react/dom on the trigger and call bindTooltips() once: the same tooltip, delay and keyboard behavior. Never a homemade data-tip tooltip: the design system audit counts those as look-alikes.
Not for
- Information users need to complete a task: show it inline or in a Popover. Tooltips are invisible on touch screens.
- Interactive content (links, buttons): tooltips cannot be reached. Use Popover.
- Repeating a visible label: it adds noise.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Match the trigger's label
IconButton label="Copy token name" and the tooltip "Copy token name": what users see and hear is the same.
Tooltips on disabled buttons to explain why
Disabled buttons do not receive focus, so keyboard users never see it. Explain inline instead.
Accessibility
- Base UI treats tooltips as visual labels: the trigger must carry the accessible name (IconButton label), which screen readers announce. The popup is not announced.
- Opens on hover after the provider delay (500ms) and immediately on keyboard focus; Escape dismisses it.
- The trigger must be focusable: wrap a Button, IconButton or Link, never plain text.
- Inverse surface (tooltip.bg, tooltip.text) passes 4.5:1 in both themes.
Content guidelines
- A few words, sentence case, no period.
- For icon buttons: the action ("Delete token"), not the icon name ("Trash").
- Keyboard shortcuts can follow the label: "Copy token name (C)".
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/Tooltip/Tooltip.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Positioning layer (layer.tooltip)
.positioner - Surface (tooltip.bg, tooltip.text, tooltip.radius)
.tooltip - Surface (tooltip.bg, tooltip.text, tooltip.radius)
.tooltip[data-instant] - Surface (tooltip.bg, tooltip.text, tooltip.radius)
.tooltip[data-ending-style]
Motion and interaction
Tooltip animates on open and close. Try it in the preview at the top.
| When | What changes | Duration | Easing |
|---|---|---|---|
| Open | Fade and movement | motion.duration.fast150 ms | motion.easing.enterstarts fast, lands softly |
| Close | Fade and movement | motion.duration.fast150 ms | motion.easing.exitstarts softly, leaves fast |
With reduced motion turned on, every change happens at once.
It also uses motion.duration.instant for motion this table does not list yet.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/Tooltip/Tooltip.tsx, so this table cannot drift from the code.
| Prop | Type | Default | Description |
|---|---|---|---|
contentrequired | ReactNode | none | The tooltip text. Short, plain, no interactive content. |
childrenrequired | ReactElement | none | The trigger: a focusable element that forwards its ref and spreads props (Button, IconButton, Link). |
side | 'top' | 'bottom' | 'left' | 'right' | 'top' | Preferred side. Default `top`. |
align | 'start' | 'center' | 'end' | 'center' | No description in the code yet. |
delay | number | none | Hover delay in ms for this tooltip; otherwise the TooltipProvider delay applies. |
open | boolean | none | No description in the code yet. |
defaultOpen | boolean | none | No description in the code yet. |
onOpenChange | (open: boolean) => void | none | No description in the code yet. |
disabled | boolean | false | Turn the tooltip off without unwrapping the trigger. |
className | string | none | No description in the code yet. |
Comes with TooltipProvider, each accepting native <div> attributes.
Playground
Tooltip has no typed options to play with: it is a container. Compose it with TooltipProvider and any native attribute. Here it is in both themes.
Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Tooltip in Storybook).
Embed Storybook stories here (3)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
Toolbar
AllStates
From the code Generated from the component, not editable here.
Changelog
- New
The measure now writes the Figma sets drawn under a component's folder as their own entries, so Claude can fix them: popups drawn open (Dialog/Popup, AlertDialog/Popup, Drawer/Popup, Menu/Popup, Popover/Popup, Tooltip/Popup, and Select/Popup or Combobox/Popup, measured open when the stories show them closed) and sets that fix a prop (Pagination/Full, Pagination/Compact, Progress/Linear)
v1.0.0, Nov 11, 2026
- New
Overlays: Dialog (sizes, scrolling body, footer, close last in focus order), AlertDialog (destructive confirmations, async confirm), Drawer (start, end, bottom with swipe), Popover, Tooltip with TooltipProvider, Menu (icons, shortcuts, groups, submenus, checkbox and radio items, danger items)
v1.0.0, Nov 11, 2026
- Fix
Compare with code: popup examples with HTML elements (a list, a paragraph) are compared instead of skipped, a tooltip is rendered with its trigger instead of failing, a size difference is said first ("height 89 in Figma vs 48 in code") instead of a small pixel score, and the list says "Show all 57 compared" next to a headline that counts every set
v1.0.0, Nov 11, 2026
- Fix
When a change cannot be read, the Live product and This change tooltip says what helps: open it from Studio when this page may not read it (or GitHub limits reads from the page), and reload only when the read failed on the way
v1.0.0, Nov 11, 2026
- Fix
Library review List: a piece decided on its own (two ways, a removal) shows its checkbox off, with a tooltip saying why
v1.0.0, Nov 11, 2026
- Fix
How Bridge compares: three marks (does it, does part of it, does not) instead of two, with the reason for each half mark in a tooltip and on /compare/
v1.0.0, Nov 11, 2026