Tooltip
StableA short text label that appears on hover and on keyboard focus.
Also known as hint, tip, hover text
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
On an icon button
<Tooltip content="Copy reply">
<IconButton label="Copy reply"><CopyIcon width={16} height={16} /></IconButton>
</Tooltip>The tooltip repeats the button name for sighted mouse users. The button keeps its own label.
When to use it
A short extra hint for a control, such as the name of an icon button. It is a bonus for people with a mouse or keyboard. Everything it says must also be available some other way.
Made of: Trigger · Tip
Use it for
- Naming an icon-only button for people who hover over it.
- A short reminder of what a control does.
- Telling people about a shortcut next to the control.
Do and avoid
Do
- Keep it to a few words.
- Use it on controls that have little or no visible text.
- Place it so it does not cover what the person is trying to read.
- Give the trigger its own name and use the tooltip only as extra.
Avoid
- Do not put essential information, errors or instructions in it.
- Do not put links, buttons or other controls inside it.
- Do not use it on something that cannot take focus.
- Do not use it to show a longer explanation. Use a Popover or text on the page.
On a phone
- Hover is ignored on touch screens, so the tip never shows from a touch alone.
- It still shows when the control gets focus, but do not rely on that: put anything the user must know in visible text.
- The tip is at most 16rem wide and wraps.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| contentrequired | string | none | Plain text for the tip. No markup, links or buttons. |
| childrenrequired | ReactElement | none | The trigger. It gets aria-describedby added, so it must accept that prop and be focusable. |
| side | "top" | "bottom" | "left" | "right" | "top" | Which side of the trigger the tip appears on. It does not flip when space runs out. |
| delay | number | 400 | Milliseconds to wait before a hover shows the tip. Focus shows it at once. |
| className | string | none | Classes for the tip itself. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one Tooltip switches all of this from its properties panel, across 4 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| State | Hover, Pressed and Focus come from the browser. | Default, Hover, Pressed, Focus |
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- hover
- The tip appears after the delay when the pointer rests on the trigger, and stays while the pointer is on it or on the tip.
- focus
- The tip appears at once when the trigger gets keyboard focus and hides when focus leaves.
- dismissed
- Escape hides the tip without moving focus.
- touch
- On coarse pointers a tap or hover does not show the tip.
Tokens
Change one of these and every part that uses it follows.
--fg--bg--shadow-md--animate-fade
Built in
- The tip has role tooltip and is linked to the trigger with aria-describedby, so screen readers read it as a description.
- It is always in the page, hidden until shown, so the description is available even before it appears.
- Hover shows it after the delay. Keyboard focus shows it at once. Blur, moving the pointer away and Escape hide it.
- Escape closes the tip and leaves focus where it was.
- The pointer can move onto the tip without it closing.
- On touch screens (coarse pointer) a tap does not show it. It can still show on keyboard focus.
- The fade runs only when motion is allowed. Forced-colors mode adds a border.
What you need to do
- Never put essential information in a tooltip. Touch users do not see it.
- The trigger must be focusable, such as a button or a link. A tooltip on plain text cannot be reached by keyboard.
- An icon-only trigger still needs its own accessible name. The tooltip adds a description, it does not replace the name.
- Keep it to a few words. Long text belongs on the page or in a Popover.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide