Code example
Common baseline
tooltip role on the popup
The tooltip element must have role="tooltip".
Connect to trigger via aria-describedby
The triggering element must reference the tooltip id via aria-describedby.
Dismiss with Escape
Pressing Escape must dismiss the tooltip.
Show tooltip on focus as well
The tooltip must appear on both hover and keyboard focus, not hover alone.
No focusable content inside
Tooltip content must not contain interactive elements (links, buttons), as they would be unreachable.
Keep tooltip visible while hovering it
The tooltip must remain visible when the user moves the mouse over it.
Show after a short delay
Introduce a short delay (e.g., 300ms) before showing the tooltip to reduce distraction.
Do not put interactive content in tooltips
Interactive content (links, buttons) inside a tooltip cannot be reached with keyboard or screen readers.
Do not rely on title attribute alone
The HTML title attribute is not reliably announced by screen readers. Use role="tooltip" with aria-describedby.
Design system implementations
Additional checks
Set enterDelay to 300ms or more
Set enterDelay to at least 300ms to prevent accidental tooltip display. The default value of 100ms may be too short.
aria-label required on icon-only button triggers
The Tooltip title supplements the visible description but does not replace an accessible name. Always provide aria-label on icon-only buttons.
Implement forwardRef for custom children
Tooltip injects DOM event listeners into its children. Custom components used as children must implement React.forwardRef to pass the ref correctly.
Code sample
Implementation notes
- –MUI Tooltip automatically sets role="tooltip" and aria-describedby.
- –enterDelay (default 100ms) controls show delay; leaveDelay (default 0ms) controls hide delay.
- –To show a tooltip on a disabled button, wrap the button in a <span> — disabled buttons do not receive pointer events.
- –Custom children components must implement React.forwardRef for event listeners to attach correctly.