How to build an accessible Tooltip in React

The floating element uses role="tooltip" and is linked to the trigger via aria-describedby only while visible; it shows on both hover and keyboard focus so it is reachable without a pointer.

When to use a Tooltip

• Labeling an icon-only control or clarifying a terse element on hover or focus
• Showing brief, supplementary text that is non-essential to completing the task
• Progressive disclosure of a short hint anchored to a trigger element

When not to use it

• The content is interactive (links, buttons, inputs) — use Popover
• Richer non-interactive preview content is needed — use HoverCard
• The information is essential and must always be visible — render it inline instead

Keyboard interactions

Role tooltip, verified at WCAG 2.2-AA.

• Tab
• Escape

Common mistakes

Avoid: <Tooltip content={<button>Undo</button>}><Icon /></Tooltip>

Prefer: <Popover><button>Undo</button></Popover>

Tooltips are hover/focus hints and cannot reliably hold focusable content; interactive content belongs in a Popover

Example

<Tooltip content="Copy to clipboard"><Button>Copy</Button></Tooltip>

See the full Tooltip reference →