Tooltip

Structure

The Tooltip trigger renders as an HTML <button> element by default to ensure native interactivity. When disabled, the trigger uses a <span> instead.

The Tooltip content itself renders outside of the document flow in a portal to prevent interference with other elements. It uses a plain HTML <div> with the ARIA role of tooltip so assistive technology is aware of its function.

Our Tooltip uses Floating UI for positioning and interactions, but the library also handles accessibility out of the box. Floating UI's useRole, useHover, useFocus, and useDismiss manage the Tooltip's accessible capabilities to ensure the show/hide behavior is consistent between assistive technology and mouse and keyboard users.

ARIA

table

Element	Attribute	Description
Trigger	aria-describedby	References the tooltip content's ID when the tooltip is open to provide the trigger a description.
Tooltip content	role="tooltip"	Tells assistive technology to consider the element as a tooltip. Applied by Floating UI's useRole hook with the default role of tooltip.

Interactive Elements

Never use interactive elements such as buttons and links within the Tooltip. With the nature of Tooltips being small overlays that will disappear when focus is lost, interactive elements may be tricky to access and disorienting for users when the document's focus order shifts on its appearance.

If adding an interactive element is required, consider adding content outside of the Tooltip or using the Popover component instead. For more information regarding our decision, see the Tooltip's Slack conversation.

Keyboard

table

Key	Function
Tab	Moves focus to the next focusable element. Opens the Tooltip when focused.
Shift+Tab	Move focus to the previous focusable element. Closes the Tooltip if open.
Escape	Closes the tooltip if open.