Tooltip
A short line of text that appears when a control is hovered or focused. Use it to add to a label the reader can already see, never to hold something they need, and never for anything they would want to click.
Live preview
Rendered by the component itself from the same generated tokens as the rest of the site.
<Tooltip
content="Copies the hex value to the clipboard"
>
<Button>Copy</Button>
</Tooltip>Installation
Install it with the shadcn CLI, along with everything it uses. New project? Set it up first, as Quick start shows.
npx shadcn@latest add https://www.graphite-ui.com/r/tooltip.jsonimport { Tooltip } from '@/components/ui/tooltip'Anatomy
A trigger, which is any focusable element you pass as the child, and the content, which is a string. It is a string rather than a node on purpose: a tooltip with a link in it is a Popover.
- TriggerRequiredAny focusable element. With type definition it is the term as text, and the Tooltip renders the kit's dotted-underline button for it.
- ContentRequiredShort text only.
Variants
Type sets the bubble’s padding, caret and gap: Standard for a labelled control, Icon button for an icon-only one, Definition for a term in running text. Placement chooses the side, and align where along the trigger the bubble sits above or below it; the caret stays on the trigger either way. It does not flip when it runs out of room.
API reference
Generated from the contract, versioned with it, and checked by drift-check. This table cannot describe props the component does not have.
| Prop | Type | Default | Notes |
|---|---|---|---|
| placement | 'top' | 'bottom' | 'left' | 'right' | — | The kit's Position. Definition opens above or below only; left and right fall back to bottom. |
| align | 'start' | 'center' | 'end' | — | The kit's Alignment, for top and bottom. The caret stays on the trigger's centre; start and end put it 16 from that edge of the bubble. |
| type | 'standard' | 'icon' | 'definition' | — | The kit's Type. Standard is padded 16 with the 12 by 6 caret 8 from the trigger. Icon, for an icon-only button, is padded 2 by 16, at least 64 wide, with the 8 by 4 caret 4 away. Definition is padded 8 by 16 with the large caret 4 away. |
| delay | — | — | Behaviour the kit cannot draw; the code keeps it. |
Design tokens
Every swatch is live. Change the source color in the header and this table repaints, because it reads the same roles the component does.
on-backgroundThe bubble and caret, the kit's background-inverse. Tooltip is the overlay the kit draws inverse (overlay.md 2.0.0), so it needs no edge and no shadow.backgroundThe bubble's text, the kit's icon-inverse.textThe kit's Tooltip style, 12/16 Medium, for the bubble and the definition term.on-surface-variantThe definition term, the kit's text-secondary.secondaryThe definition term's dotted rule at rest, the kit's button-secondary.primaryThe definition term's rule on hover and focus (the kit's interactive), and its focus ring, through the family's focus step.spacingPadding per type and the gap from the trigger.radiusBubble corner.motionThe entrance fade. Opacity only — the four placement classes each carry their own `transform`, so an animation that moved would overwrite the placement.
Usage
The contract's prohibitions, written as the choices you will actually face.
Do
- Put the tooltip on something focusable, a Button or a link, so keyboard users get it as well as pointer users.
- Keep it to one short line that adds to a label the reader can already see.
- Give an icon-only button its own aria-label as well, and type="icon" for the kit’s tight bubble. The tooltip adds to the name; it does not supply it.
- Raise the delay in a dense toolbar, where tooltips would otherwise flash as the pointer crosses it.
Don’t
- Put a link or a button in the content. A tooltip you can click into is a Popover.
- Hide anything the reader needs in a tooltip. Touch screens never hover, so it must be extra, not essential.
- Wrap a disabled button. It cannot take focus, so keyboard users never see the explanation.
- Place it where the bubble would cross the edge of the screen. It will not move itself back.
Accessibility
What the component does for you, and what it leaves to you.
- Keyboard
- It opens when the trigger takes focus, after the same delay as hover, and closes on blur or Escape.
- Roles
- The bubble is
role="tooltip". While it is open, the trigger itself carriesaria-describedbypointing at it, alongside any description the trigger already had. It describes; it does not name, so keep the trigger’s own name complete. - Focus
- It never takes focus and never traps it. The trigger keeps focus the whole time.
- Pointer
- The pointer can move from the trigger onto the bubble and it stays open, so it can be read at any speed or magnified. It closes once the pointer leaves both.
- Contrast
- Text is
backgroundonon-background: the kit draws the bubble inverse, so it stands off the page in either mode without an edge. A definition term ison-surface-variantover asecondarydotted rule. - Motion
- It fades in on the fast motion step, opacity only, and appears at once under prefers-reduced-motion.
Figma parity
The kit’s Tooltip page has two public sets: Tooltip, and the Tooltip body item it is built from. Type, Position and Alignment map across; Visible is a state Figma draws because it has no other way to show it, and delay has no kit axis at all, since a frame cannot hold time.
| Kit axis | Values | Code | How it maps |
|---|---|---|---|
| Type | Standard · Definition · Icon button | type | standard, definition and icon, each with the kit’s padding (16; 8 by 16; 2 by 16), caret (12 by 6, or 8 by 4 for Icon) and gap (8, 4, 4). Definition renders its own term: on-surface-variant over a dotted secondary rule that turns primary on hover and focus. |
| Position | Top · Bottom · Left · Right | placement | One to one. Definition is drawn above and below only. |
| Alignment | Start · Center · End | align | Top and Bottom only, as drawn. Start and End put the caret 16 from that edge, on the trigger’s centre. |
| Bubble | background-inverse · icon-inverse | — | on-background with background text, no edge, a 2px corner, Tooltip type 12/16 Medium. |
| Definition: Top, Center | No bubble drawn | — | A kit slip: the variant is empty. Built from Bottom Center, as is Top Start, which the kit draws 26 off its trigger. |
| Visible | True · False | — | Runtime state. Hover and focus open it; the kit draws both because Figma cannot. |