Tooltip
Last Updated: September 2026Tooltips are hover-triggered elevated surfaces which house supported or supplemental information about the entity to which the trigger is tied. Tooltips are intended strictly for non-interactive content.
Source CodeAnatomy
link- 1Content
- 2Arrow
Variants
linkOn button
Wrap a Button; content is a short string or node.
On IconButton
Common pattern — pair content with aria-label on the icon button.
Side
Position with side: top (default), bottom, left, or right.
On text
Trigger can be any single element, including a span.
Usage Guidelines
linkWhen to use
- •To clarify icon-only controls with a short label.
- •For brief definitions or hints that shouldn't take permanent UI space.
- •When content is a single phrase — not a form or set of actions.
When not to use
- •For interactive menus or forms — use Popover, Menu, Modal, or Drawer.
- •For long help articles — link to docs instead.
- •When the information is critical — keep it visible, not hover-only.
Keep content short and match IconButton aria-label when they share meaning.
Don't put multi-sentence or interactive content in a tooltip.
Pass exactly one React element as children (the trigger).
Don't rely on Tooltip alone for the accessible name — IconButton still needs aria-label.
Behaviors
linkFlat API (not compound)
- •Public API: content, children (trigger element), side, align, sideOffset.
- •There is no Tooltip.Trigger / Tooltip.Content export — wrap Base UI internally.
- •Default side is top; default sideOffset is 8.
Open / close
- •Opens on hover and focus of the trigger; closes on blur/unhover.
- •Content is portaled with a popover surface and arrow.
Content Guidelines
linkCopy
- •Prefer 1–5 words that name the action or define the term.
- •Sentence case; no trailing period unless it's a full sentence (usually avoid).
- •Synthetic demo strings only — never real PHI in tooltip content.
Accessibility
linkText & Labels
- •Icon-only triggers need aria-label (or visible text) even when Tooltip content exists.
- •Tooltip content supplements — it does not replace an accessible name.
ARIA attributes
- •Built on Base UI Tooltip — focus opens the tip for keyboard users.
Keyboard Support
- •Tab → focus the trigger.
- •Tooltip appears on focus; Escape dismisses (Base UI behavior).
WCAG Compliance Standards
FAQs
linkIs Tooltip a compound component?
No — use <Tooltip content={...}><Trigger /></Tooltip>. Do not write Tooltip.Root / Tooltip.Trigger.
Can children be a string?
No — children must be a single React element. Wrap text in a span if needed.
Popover vs Tooltip?
Tooltip is for short non-interactive hints. Use Popover for richer or interactive content.