Tooltip
Tooltips add additional context to interactive UI elements and appear on mouse hover or keyboard focus.
Page navigation navigation
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 theEsc
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 theTooltip
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 usingaria-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 forIconButtons
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 withEsc
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 forIconButtons
- 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 aTooltip
on a disabled element, usearia-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 theEsc
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 witharia-labelledby
and hidden from the accessibility tree witharia-hidden="true"
- In the description variant, the
Tooltip
text is associated with the control witharia-describedby
and hidden from the accessibility tree witharia-hidden="true"