---
title: "Tooltip"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/tooltip"
source: "https://opsinjs.pensievelabs.org/docs/components/tooltip.md"
section: "Components"
status: "shipped"
kind: "component"
category: "overlay"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["hover label"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="tooltip"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured: footnote ink on the card fill, and the arrow's fill against whatever surface sits behind it, are argued from the roles only.&#x22;,
  &#x22;Nobody has listened to a tooltip in a screen reader, so whether the aria-describedby label is announced as a description, or at all on touch, is unheard.&#x22;,
  &#x22;Nothing stops a caller putting the one fact a control cannot be used without behind a hover a phone reader never triggers; no lint catches it.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="tooltip" unbuilt="false" importPath="@/components/ui/tooltip" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { Tooltip } from "@/components/ui/tooltip"
```

```tsx
<Tooltip content="A rolling mean across the nights you have logged.">
  <button type="button">Overnight average</button>
</Tooltip>
```

## Examples [#examples]

<ComponentPreview name="tooltip" />

### On an icon button [#on-an-icon-button]

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

<ComponentPreview name="tooltip-on-an-icon-button" kind="example" align="start" />

### A supplementary hint [#a-supplementary-hint]

The setting is named in plain words, so a touch reader needs no hover, and
`content` adds one optional sentence.

<ComponentPreview name="tooltip-a-supplementary-hint" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Expanding an icon-only control's name, already carried through aria-label.&#x22;,
  &#x22;Adding a short optional note beside a label that already stands on its own.&#x22;,
  &#x22;Surfacing a value's full form on demand, where the reading is already on screen.&#x22;,
]"
  avoid="[
  { case: &#x22;The label carries something a touch reader needs. A phone has no hover, so the tooltip never opens for them.&#x22;, instead: &#x22;callout&#x22; },
  { case: &#x22;You are explaining what a clinical word means. That belongs inline, in the accessibility tree.&#x22;, instead: &#x22;term&#x22; },
  { case: &#x22;You are attaching a hint to a form control, such as a date format. A field hint is always visible.&#x22;, instead: &#x22;field&#x22; },
]"
/>

## Accessibility [#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.

<KeyboardTable
  name="tooltip"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus onto the trigger and shows the tooltip&#x22;,
    notes: &#x22;No open delay on focus.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus off the trigger and hides the tooltip&#x22;,
    notes: &#x22;The label follows focus.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Dismisses the tooltip&#x22;,
    notes: &#x22;Focus stays on the trigger and reopens it on the next pointer rest.&#x22;,
  },
  {
    keys: &#x22;Enter, Space&#x22;,
    action: &#x22;Activates the underlying control&#x22;,
    notes: &#x22;The tooltip binds neither key.&#x22;,
  },
]"
/>

<ContrastReport component="tooltip" />

## Props interface [#props-interface]

<PropsTable name="TooltipProps" />

`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.
