Skip to content

Accessibility

The popover follows the WAI-ARIA Disclosure pattern — a trigger that shows and hides additional content, with its open state exposed through aria-expanded — and meets WCAG 2.1 AA. It comes in two forms: a tooltip that reveals short, non-interactive text on hover or focus (the Tooltip pattern), and a popover that reveals a panel of interactive content on click. Both are non-modal: focus is never trapped, the trigger keeps or regains focus, and the browser weaves the content into the tab order rather than sealing the user inside it. An accessible popover stays reachable and dismissible from the keyboard, keeps assistive technology informed of its open state, and gives its trigger and content an accessible name.

For designers

Section titled “For designers”
  • Text, icons, and their background must maintain accessible contrast on every supported surface and in both the default and contrast (is-contrast) themes. Source: WCAG 1.4.3 Contrast (Minimum).
  • State must never be conveyed by colour alone — pair it with text, an icon, or a shape. Source: WCAG 1.4.1 Use of Color.
  • Focus styles must stay visible, meet contrast requirements on every supported surface, and be clearly distinguishable from hover. Source: WCAG 2.4.7 Focus Visible.
  • Content that appears on hover or focus must be dismissable, hoverable, and persistent — a tooltip must survive the pointer moving toward it and stay until it is dismissed or focus leaves, never vanishing on a timer. Source: WCAG 1.4.13 Content on Hover or Focus.
  • Position the arrow or pointer so it clearly references the triggering element, and keep enough spacing that the panel neither overlaps the trigger nor crowds nearby controls.
  • Use semantic colour tokens (e.g. foreground/neutral/default) rather than fixed values, so the component adapts correctly across themes and surfaces.

For developers

Section titled “For developers”

Build both forms on the native HTML Popover API — the trigger carries popovertarget and the panel the popover attribute — so the browser handles the hard parts: it promotes the panel to the top layer, light-dismisses it on outside click or Escape, weaves it into the sequential tab order after the trigger, and restores focus to the trigger on close. This is deliberately non-modal, so do not add a focus trap or a manual focus-return. Use popover="auto" for the interactive popover and popover="hint" for the tooltip, so a tooltip can surface without dismissing an open popover. A tooltip holds only short, non-interactive text and never takes focus — if the content needs a link or button, use a popover instead. Keep decorative icons out of the accessibility tree with aria-hidden="true". Each element’s role, accessible name, and state are in the Labelling elements section below.

Keyboard interaction

Section titled “Keyboard interaction”
Key Action
Enter / Space With the trigger focused, open or close the popover
Escape Dismiss the open popover or tooltip and return focus to the trigger
Tab / Shift + Tab Move into the open popover and through its content, then on to the next / previous control — focus is never trapped

A tooltip appears when its trigger receives focus (or hover) and hides on blur, pointer-leave, or Escape; it never receives focus itself. All triggers and controls must be fully operable from the keyboard. Source: WCAG 2.1.1 Keyboard. Interactive targets must be at least 44 px high for comfortable touch use — comfortably clearing the WCAG AA minimum. Source: WCAG 2.5.8 Target Size (Minimum).

Labelling elements

Section titled “Labelling elements”

Give every element the role, name, and state assistive technology needs. The two forms share one design but carry different semantics, so they are documented separately — each demo stacks the trigger with the surface it opens.

Popover

Section titled “Popover”

The interactive form: a role="dialog" panel of controls. Its content slot is a placeholder, since consumer-slotted content carries its own component’s semantics.

  1. Popover trigger
  2. Popover
  3. Close button

Popover trigger

A button carrying popovertarget to toggle the panel. Keep aria-expanded in sync with the open / closed state — the recipe updates it on the panel’s toggle event. Name an icon-only trigger with aria-label; otherwise its text content is its name.

Popover

role="dialog" on the panel. Name it with aria-labelledby pointing at the visible title, or aria-label when there is no title — a dialog with no name announces only as “dialog”.

Close button

An icon-only button with popovertarget set to the panel’s id so it closes the panel. Give it aria-label="Close"; its icon is decorative.

Tooltip

Section titled “Tooltip”

The descriptive form: a role="tooltip" bubble of short, non-interactive text. The text is intrinsic and is the accessible description — there is no content slot and nothing inside takes focus.

Battery range is measured on the WLTP cycle.

  1. Tooltip trigger
  2. Tooltip

Tooltip trigger

Link the trigger to the tooltip with aria-describedby pointing at the tooltip’s id, so the text is announced as a description when the trigger is focused. Name an icon-only trigger with aria-label.

Tooltip

role="tooltip" on the bubble; its text content is the description. It is not focusable and takes no name of its own.

Source: WCAG 4.1.2 Name, Role, Value.