Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
tooltip · base base · style base-lyraOpen under the product theme

On an icon button

Each icon button carries its own name through aria-label; content repeats it visibly. The labels name fictional actions.

Theme
Density
Text
Status
Accent theme
Accent
tooltip-on-an-icon-button · base base · style base-lyraOpen under the product theme
tooltip-on-an-icon-button.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
tooltip-a-supplementary-hint · base base · style base-lyraOpen under the product theme
tooltip-a-supplementary-hint.tsx
import { 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 callout instead.
  • You are explaining what a clinical word means. That belongs inline, in the accessibility tree.Use term instead.
  • You are attaching a hint to a form control, such as a date format. A field hint is always visible.Use field instead.

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 content stays supplementary.
  • The popup's non-text contrast (SC 1.4.11) is the shared border-border role 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.
KeyActionNotes
TabMoves focus onto the trigger and shows the tooltipNo open delay on focus.
Shift+TabMoves focus off the trigger and hides the tooltipThe label follows focus.
EscapeDismisses the tooltipFocus stays on the trigger and reopens it on the next pointer rest.
Enter, SpaceActivates the underlying controlThe tooltip binds neither key.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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.