Skip to content

Tooltip

Considerations for designers & developers

  • When open, tooltips shouldn't block a user from performing any task on the page.
  • Avoid using tooltips with non-interactive elements as triggers (especially text, but icons as well), because such tooltips aren't accessible for keyboard users who don't use a screen reader.
  • If your tooltip appears on hover/focus, don't put focusable elements in it. If you must have interactive elements in the tooltip, use components that open on click/Enter/Space, such as DescriptionTooltip or Dropdown.
  • Whenever possible, use descriptive text on your form fields that doesn't need to be activated by a focus or hover event. Tooltips can be problematic for some assistive technologies.

This list will help you keep in mind the necessary roles and attributes to make our components fully accessible in the particular cases in your interfaces.

Hint recommended roles and attributes
ComponentUse caseAttributes
HintIf the trigger is a non-interactive icon.Set aria-hidden="false" for Trigger if it's merged with the icon, otherwise set it for the icon. Example.
TooltipIf an interactive element is nested and not merged with Trigger.Set aria-describedby and role to undefined for Trigger, and instead assign the value you get from the children render function to the nested element's aria-describedby. Example.
Tooltip, DescriptionTooltipIf the trigger doesn't have a visible label.Set aria-label for Trigger, or the nested element if it isn't merged, to reflect trigger's name or goal. For Informer use something like "About {feature}". Example.
DescriptionTooltipAlways.Set aria-label for Popper to reflect what this tooltip is about. Can be similar to trigger's accessible name. Example.

What component has

Keyboard support

Keyboard support
KeyFunction
EscCloses the tooltip.
SpaceEnterOpens DescriptionTooltip.
TabIn Hint and Tooltip without nested interactive elements — moves focus to the next focusable element outside of the tooltip.
In an open DescriptionTooltip and Tooltip containing interactive elements — moves focus to the next focusable element inside the tooltip and, in the end, back to the trigger.
Shift + TabMoves focus in reverse relative to Tab.

Focus behavior

Focus behavior
ComponentTrigger behaviorPopper behavior
HintTriggers popper on focus.Popper isn't focusable.
TooltipTriggers popper on focus.Popper isn't focusable by default, but becomes focusable if there are any focusable elements inside.
DescriptionTooltipNothing happens on focus.Popper is focusable by default and receives focus automatically when opened.

WARNING

Although it's technically possible to use interactive elements inside a Tooltip, it's not recommended due to poor usability. Consider using DescriptionTooltip or Dropdown if it must contain links or other interactive elements.

Hint default attributes

The following list describes roles and attributes the component already has.

Hint default attributes
ComponentAttributeUsage
Triggeraria-labelSets the accessible name of the Trigger to the same text value as the Popper content.
Popperaria-hiddenPopper is hidden from assistive technologies.

Tooltip default attributes

The following list describes roles and attributes the component already has.

Tooltip default attributes
ComponentAttributeUsage
Triggeraria-describedby="IDREF"Allows assistive technologies to announce popper content as trigger's description.
Popperrole="tooltip"Indicates that this is a container with tooltip's content.
Popperaria-live="polite" (except for theme="warning")Ensures compatibility with browsers and screen readers that doesn't support aria-describedby . Assistive technologies will announce popper content when it's opened or changed.
Popperaria-live="assertive" (only with theme="warning")Like aria-live="polite", but will interrupt any other announcement a screen reader is currently making.

DescriptionTooltip default attributes

The following list describes roles and attributes the component already has.

DescriptionTooltip default attributes
ComponentAttributeUsage
Triggeraria-controls="IDREF"Indicates which element this Trigger opens.
Triggeraria-expandedSet to true when Popper is visible. Indicates that the popup is open.
Triggeraria-haspopup="dialog"Indicates that the element triggers a dialog.
Popperrole="dialog"Identifies the element as a dialog, indicating to assistive technology that its content is grouped and separated from the rest of the page content.

Other recommendations

See more accessibility recommendations in the common Accessibility guide.

Released under the MIT License.

Released under the MIT License.