Tooltip
A short label that appears beside an element after the pointer rests on it, or when it takes keyboard focus.
import { Tooltip } from "@butteryui/react";Demo
Rest the pointer on Export, or tab to it, to see “Saves a 2× PNG to your downloads” on its top side.
When to use it
Use it for
- Naming an icon-only action (IconButton shows one for you)
- A brief hint on a control whose label is clipped or terse
Not for
- Anything people need to do their task: put it on the page
- Content with links or buttons: use Popover
- Errors and confirmations: show them inline or in a toast
Examples
Export hint
A hint on a button whose label is short.
Print settings
Tooltips that explain terse labels in an inspector, shown as each field takes focus.
Show me where
A tooltip whose open state the example keeps, so a tip elsewhere can open it to point out a button.
Slides export as PNG files.
Shown below
A tooltip that opens under its button, for controls at the top of a window.
Edited just now
Variants and states
On hover and focus
Rest the pointer on a button for half a second, or tab to it. Escape closes the tooltip.
Props
Tooltip
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What it says: a short name or hint. Never put something people need only in a tooltip. | |
childrenrequired | ReactElement | The element it describes, such as an IconButton. It has to pass on a ref and its event handlers. | |
side | "top" | "right" | "bottom" | "left" | "top" | Which side it opens on. Defaults to "top"; it flips when there isn't room. |
open | boolean | Whether it's open. Pair with onOpenChange to control it. | |
defaultOpen | boolean | false | Whether it starts open when uncontrolled. Defaults to false. |
onOpenChange | ((open: boolean) => void) | Called when it opens or closes. | |
describes | boolean | true | Whether it describes its element to screen readers while it's open. Defaults to true; turn it off
when it only repeats the element's name, as IconButton's does. A description the element was given
stays either way. |
className | string | Extra classes for the tooltip itself. |
Tooltip.Provider
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | The part of the app whose tooltips share the hover intent. |
Accessibility
Opens after 500ms of hover and at once on keyboard focus; Escape closes it. Its text describes its element (aria-describedby) unless describes is off, for a tooltip that only repeats the element's name. It never takes focus and holds no interactive content.
| Keys | What they do |
|---|---|
| Tab | Opens it at once as focus reaches its element |
| Escape | Closes it, leaving focus on its element |
Motion
It appears with a `Presence` preset and leaves faster than it came, in about 60% of the time.
With reduced motion: It appears at once instead of fading in.
Layout
It opens 6px from its element, on top unless side says otherwise, and flips when there's no room, staying 8px inside the window. It's as wide as its label up to --bt-w-inspector (340px) or the room the window leaves, wrapping the label in balanced lines past that, and it holds no controls, so it has no hit area of its own.