Tooltip

Accessibility and usability expectations

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.

Tooltips must be operable with a keyboard alone, without requiring the use of a mouse or other pointing device.

A Tooltip must be postioned next to the element that triggers it, so that it is visually obvious which element the Tooltip is associated with.

When activated with the cursor, a Tooltips must remain visible whilst the cursor is over the Tooltip and the element that triggers it, and close when the cursor is moved away.

When activated by an element recieving focus, the Tooltip must remain visible whilst the element has focus, and close when the Esc key is activated and when focus is moved away from the element that triggers it.

When the element that triggers a Tooltip has focus it must have a focus indicator, which should be our global focus indicator styling, and must not be hidden by the Tooltip. If the focus indicator is not the browsers default, and relies on colour alone, then it must meet the minimum color contrast ratio of 3:1 against the background.

A Tooltip's text and boundary must have sufficient colour 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.

Label variant

The label variant of the Tooltip component uses hidden text that is associated with the control that triggers it using aria-labelledby as the content for the Tooltip. It provides the accessible name for the control.

The label should be concise and descriptive of the purpose of the control.

The label variant of the Tooltip must not be used on controls that have a permanently visible label.

Description variant

The description variant of the Tooltip component uses hidden text that is associated with the control that triggers it using aria-describedby. It provides the accessible description for the control.

The description should be concise and must not include any essential content, as not all users will be able to access the content.

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 minumum colour 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 Tooltips to visually surface the label for IconButtons.

Never include Tooltips on non-interactive components (div, span, p) because it will not be accessible for keyboard or screen reader users.

Tooltips are 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.

Tooltips 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

• Tooltips only appear on interactive elements
• Tooltips do 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 colour contrast requirements
• The Tooltip contains only string content
• Label Tooltips are not used on controls that have a visible label
• For label Tooltips, the label is concise and descriptive of the purpose of the control
• For description Tooltips, the descritption 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"