Tooltip

Tooltip content is easily missed as there is no indication that a Tooltip is available until a user directly interacts with a control. Tooltips are not accessible for touch screen users as they are only seen as the element that triggers it is being pressed. Tooltips are not always available to screen reader users such as when navigating with the arrows keys in browse mode.

It is not recommended to use a Tooltip if there is another, more accessible way to convey the information. Consider alternatives to tooltips before using this component.

The primary purpose of the Tooltip component is to provide a visible label for IconButtons.

Accessibility and usability expectations

Presentation

Cognition

• For the Label variant, the label should be concise and descriptive of the purpose of the control
• For the Description variant, the description should be concise and must not include any essential content, as not all users will be able to access the content

Vision

• A Tooltip must be positioned next to the element that triggers it, so that it is visually obvious which element it is associated with
• The Tooltip text and boundary must have sufficient color contrast against the background
• The text in a Tooltip must remain readable and not require horizontal scrolling when resized or zoomed to 400% or viewed on a viewport of 320px
• When the element that triggers a Tooltip has focus, it must have a visible focus indicator. If the indicator is custom and relies on color alone, it must meet a minimum contrast ratio of 3:1 against the background

Mobility

• A Tooltip must be operable with a keyboard alone, without requiring the use of a mouse or other pointing device

Adaptability

• The text in a Tooltip must remain readable and not require horizontal scrolling, at a viewport size of 320 by 256 CSS pixels

Interaction

Keyboard

• When activated by an element receiving focus, the Tooltip must remain visible while the element has focus
• The Tooltip must close when the Esc key is pressed or focus is moved away from the trigger element

Pointer device

• When activated with the cursor, the Tooltip must remain visible while the cursor is over the Tooltip or the triggering element, and close when the cursor moves away

Engineering for AT Compatibility

Screen reader

• The label variant of the Tooltip uses hidden text associated with the control using aria-labelledby, providing the accessible name for the control
• The label variant must not be used on controls that already have a permanently visible label
• The description variant uses hidden text associated using aria-describedby, providing the accessible description
• The Tooltip component’s primary purpose is to provide a visible label for IconButtons

Built-in accessibility features

• The component handles all aspects of hover and keyboard interaction, and ensures that the content is readable when resized and zoomed
• The Tooltip can be dismissed with Esc without moving the focus or pointer away from the trigger element
• The Tooltip text and boundary meets minimum color contrast requirements
• The content is conveyed to screen readers by use of the accessible name of the trigger control for the label variant, and the accessible description for the description variant

Implementation requirements

• Reserve Tooltip to visually surface the label for IconButtons
• Never include a Tooltip on non-interactive components (<div>, <span>, <p>) because it will not be accessible for keyboard or screen reader users
• A Tooltip is not allowed on disabled elements because such elements are not keyboard-accessible. If you must set a Tooltip on a disabled element, use aria-disabled="true" instead and programmatically disable the element
• A Tooltip should only hold string content, as structural information is not available to screen readers via the accessible name and accessible description

How to test the component

Integration tests

• A Tooltip only appear on interactive elements
• A Tooltip does not appear on disabled elements, but can appear on inactive elements
• When the element that triggers a Tooltip has focus, it has a focus indicator that meets color contrast requirements
• The Tooltip contains only string content
• A label Tooltip is not used on controls that have a visible label
• For a label Tooltip, the label is concise and descriptive of the purpose of the control
• For a description Tooltip, the description is concise and contains only non-essential text

Component tests

• The Tooltip appears next to the trigger control when the control is hovered or focused
• The Tooltip remains visible whilst the cursor is over the Tooltip and the interactive control, and closes when the cursor is moved away
• The Tooltip remains visible whilst the trigger control has focus and closes when the Esc key is activated and when focus is moved away from the trigger control
• The Tooltip text has sufficient contrast, at least 4.5:1, against the background
• The Tooltip text can be resized to 200% and remain readable
• When viewed at 400% or on a 320px viewport, the Tooltip text remain readable and does not require horizontal scrolling
• In the label variant, the Tooltip text is associated with the control with aria-labelledby and hidden from the accessibility tree with aria-hidden="true"
• In the description variant, the Tooltip text is associated with the control with aria-describedby and hidden from the accessibility tree with aria-hidden="true"