Components
Tooltip
A short supplementary label that appears when a pointer rests on a control or a keyboard moves focus to it, for information a reader can do without.
Usage
pnpm dlx shadcn@latest add @opsinjs/tooltip
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Tooltip } from "@/components/ui/tooltip"<Tooltip content="A rolling mean across the nights you have logged.">
<button type="button">Overnight average</button>
</Tooltip>Examples
tooltip · base base · style base-lyraOpen under the product themeOn an icon button
Each icon button carries its own name through aria-label; content repeats it
visibly. The labels name fictional actions.
tooltip-on-an-icon-button · base base · style base-lyraOpen under the product themeimport { CalendarPlus, Share2 } from "lucide-react"
import { Tooltip } from "@/components/ui/tooltip"
const ICON_BUTTON =
"inline-flex aspect-square items-center justify-center rounded-opsin-md border border-border bg-card " +
"min-h-(--opsin-target-minimum,2.75rem) min-w-(--opsin-target-minimum,2.75rem) " +
"[color:var(--foreground)] cursor-pointer " +
"transition-colors duration-(--opsin-duration-fast) ease-opsin-standard hover:bg-state-hover " +
"focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)] focus-visible:outline-ring"
export default function TooltipOnAnIconButton() {
return (
<div className="flex items-center gap-opsin-2">
<Tooltip content="Add to your calendar">
<button type="button" aria-label="Add to your calendar" className={ICON_BUTTON}>
<CalendarPlus aria-hidden="true" className="size-[1.25em]" />
</button>
</Tooltip>
<Tooltip content="Share with your team">
<button type="button" aria-label="Share with your team" className={ICON_BUTTON}>
<Share2 aria-hidden="true" className="size-[1.25em]" />
</button>
</Tooltip>
</div>
)
}A supplementary hint
The setting is named in plain words, so a touch reader needs no hover, and
content adds one optional sentence.
tooltip-a-supplementary-hint · base base · style base-lyraOpen under the product themeimport { Info } from "lucide-react"
import { Tooltip } from "@/components/ui/tooltip"
export default function TooltipASupplementaryHint() {
return (
<div className="inline-flex items-center gap-opsin-2 text-opsin-body [color:var(--foreground)]">
<span>Quiet hours</span>
<Tooltip content="Reminders wait until the morning during the hours you set here.">
<button
type="button"
aria-label="About quiet hours"
className={
"inline-flex aspect-square items-center justify-center rounded-full border border-border bg-card " +
"min-h-(--opsin-target-minimum,2.75rem) min-w-(--opsin-target-minimum,2.75rem) " +
"[color:var(--muted-foreground)] cursor-pointer " +
"transition-colors duration-(--opsin-duration-fast) ease-opsin-standard hover:bg-state-hover " +
"focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)] focus-visible:outline-ring"
}
>
<Info aria-hidden="true" className="size-[1.25em]" />
</button>
</Tooltip>
</div>
)
}When to use it
Use it when
- Expanding an icon-only control's name, already carried through aria-label.
- Adding a short optional note beside a label that already stands on its own.
- Surfacing a value's full form on demand, where the reading is already on screen.
Do not use it when
- The label carries something a touch reader needs. A phone has no hover, so the tooltip never opens for them.Use
calloutinstead. - You are explaining what a clinical word means. That belongs inline, in the accessibility tree.Use
terminstead. - You are attaching a hint to a form control, such as a date format. A field hint is always visible.Use
fieldinstead.
Accessibility
Base UI wires the popup through aria-describedby, so the label is a
description, never a replacement for the control's own name. Focus opens the
tooltip, Escape dismisses it without moving focus, and the label follows focus
off the trigger. On hover it unfolds from the trigger, while a tooltip opened by focus,
or moved to from a neighbour, appears at once. Under prefers-reduced-motion only a
short crossfade remains. Text sits at the footnote step with no px size, and it
takes neither colour axis: no status colour, no colour literal and no ramp step.
Axe, target-size, focus-visible and 320px clipping checks were clean, and
tooltip.tsx needed no change.
Residual items.
- A tooltip is unreachable on a hover-less touch device, so
contentstays supplementary. - The popup's non-text contrast (SC 1.4.11) is the shared
border-borderrole token, reasoned rather than measured. - The popup staying hoverable across the gap (SC 1.4.13) is a Base UI 1.7.0 default, not a manual trace.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus onto the trigger and shows the tooltip | No open delay on focus. |
| Shift+Tab | Moves focus off the trigger and hides the tooltip | The label follows focus. |
| Escape | Dismisses the tooltip | Focus stays on the trigger and reopens it on the next pointer rest. |
| Enter, Space | Activates the underlying control | The tooltip binds neither key. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from TooltipProps in registry/bases/base/tooltip.tsx.
content is required; an empty one raises a development warning. children
must be focusable. side defaults to top and Base UI flips it at the screen
edge. delay defaults to 600 and governs the pointer only; focus opens the
tooltip at once.