- Both Tooltip and Popover must comply with WCAG 2.1 (1.4.3, 1.4.13, 2.1.1) and EN 301 549 standards.
- Ensure a minimum contrast ratio of 4.5:1 between text and background.
- Tooltip: Triggered by hover or focus, dismissed on blur or Escape. Must be accessible via keyboard and announced using
aria-describedby.
- Popover: Triggered by click or tap, dismissed via close button, external click, or Escape. Browser-managed focus: the popover is inserted into the tab order after the trigger, and focus returns to the trigger on close. Include
aria-labelledby when a title is present.
- Always position the pointer or arrow so it clearly references the triggering element.
- Maintain consistent spacing and elevation across brands and viewports.
- Ensure sufficient colour contrast between text, icons, and background (minimum ratio 4.5:1, WCAG 2.1 AA).
- Both Tooltip and Popover must remain fully readable and dismissible across light and dark themes.
- Tooltip text should not rely solely on colour or animation to convey meaning.
- Maintain clear spacing between Tooltip or Popover and the triggering element.
- Avoid placing interactive elements too close to the Tooltip or Popover to prevent focus traps.
- Ensure consistent alignment, padding, and border radius according to tokenised structure.
- Focus styles must remain visible and meet WCAG AA contrast requirements across all supported surfaces. Focus should be clearly distinguishable from hover.
- Colour tokens used within the component should be semantic (e.g.
color-foreground-neutral-default) rather than fixed values. This ensures the component adapts correctly to different themes or surfaces.
- Tooltip and Popover must be fully accessible via keyboard.
- Tooltips should appear on focus and hover, and dismiss on blur or Escape.
- Popovers should rely on the native Popover API for focus management — the browser inserts the popover into the tab order after the trigger and restores focus to the trigger on close. Avoid implementing custom focus traps.
- Use
aria-describedby for tooltips and aria-labelledby or aria-controls for popovers when referencing content.
- Decorative icons must be marked with
aria-hidden="true".
- Each interactive element inside a Popover must be reachable and operable via keyboard.
- Ensure all instances are tested through automated accessibility tools (e.g. Axe, Lighthouse) before release.
- Manually verify focus order and visibility in both themes to confirm expected behaviour.
- Tooltips — use
role="tooltip" and link them to their trigger with aria-describedby.
- Popovers with interactive content — use
role="dialog" (or role="alertdialog" when the user must acknowledge something). Link the trigger to the popover with aria-controls or use popovertarget.
The Popover API provides built-in accessibility benefits — including focus management, light-dismiss, and top-layer promotion — without custom JavaScript.
| Attribute | Behaviour |
|---|
popover (or popover="auto") | Light-dismiss enabled. Opening one auto popover closes other open auto popovers (unless they are nested or ancestral). |
popover="manual" | No light-dismiss. Must be closed explicitly via popovertarget or JavaScript. |
popover="hint" | Light-dismiss enabled. Hint popovers do not close auto popovers — allowing a tooltip to appear while a menu or dialog popover is still open. Only one hint popover can be open at a time. Ideal for tooltips. |
| Key | Action |
|---|
| Tab | Moves focus into and out of the popover. For auto and hint popovers the browser updates the tab order automatically. |
| Escape | Closes the popover (light-dismiss). When using popover="manual", implement this yourself or use a CloseWatcher. |
- Always provide an accessible name. Use
aria-label, aria-labelledby, or a visible title inside the popover bubble.
- For tooltips, ensure the trigger has
aria-describedby pointing to the tooltip’s id so the description is announced when the trigger receives focus.
- For dialog popovers, set
aria-expanded on the trigger to communicate the open / closed state.
- The Tooltip appears when its trigger element receives focus or hover.
- The Tooltip never receives focus itself — focus must always remain on the trigger element.
- It disappears automatically when focus moves away, the element is blurred, or the user presses Escape.
- When the trigger regains focus, the Tooltip reappears automatically to preserve context.
- The focus indicator on the trigger must remain visible and clearly distinguishable while the Tooltip is active.
- Tooltips must contain only short, non-interactive text. If the content requires links, buttons, or other actions, use a Popover instead.
- Focus starts on the trigger element — The trigger element (e.g. a button, icon, or link with
popovertarget) must receive focus first. The trigger must have a visible focus indicator.
- When the popover opens — Focus stays on the trigger. The browser inserts the popover into the sequential focus navigation order so the next Tab moves into the popover content. The popover content must be associated with the trigger using
aria-labelledby or aria-describedby.
- While the popover is open — Tab moves through the focusable elements inside the popover. Pressing Tab past the last focusable element moves focus to the next focusable element after the trigger in document order, as if the popover were inline at that position — popovers are not focus-trapped. Pressing Escape closes the popover (light-dismiss). For
popover="auto", clicking outside the popover also closes it.
- When the popover closes — Focus returns to the original trigger element automatically. The trigger’s focus ring should remain visible.
