Accessibility

The component covers two patterns, and which one applies is decided by the form you reach for. The interactive toggletip is a Disclosure — a trigger that shows and hides a panel, with its open state exposed on the trigger — and the panel itself is a non-modal dialog. The read-only tooltip is the Tooltip pattern: supplemental text attached to a trigger, never focusable, never interactive. Both meet WCAG 2.1 AA. Neither is modal: focus is not trapped, the trigger keeps or regains it, and the browser weaves the panel into the tab order rather than sealing anyone inside it. An accessible toggletip stays reachable and dismissible from the keyboard, keeps assistive technology informed of its open state, and gives its trigger and its surface an accessible name.

For designers

• Text, icons and their background must meet contrast on every supported surface, in both the neutral and contrast (is-contrast) schemes. Normal text needs 4.5:1 and large text 3:1, and the overlay’s own background or border needs 3:1 against the page behind it so its edge is discernible. Source: WCAG 1.4.3 Contrast (Minimum).
• State must never be carried 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, clear hover, and reach 3:1 against their surroundings on every supported surface. Source: WCAG 2.4.7 Focus Visible.
• Content shown on hover or focus must be dismissible, hoverable and persistent — a tooltip has to survive the pointer travelling towards it, and stay until it is dismissed or focus leaves. Never hide one on a timer. Source: WCAG 1.4.13 Content on Hover or Focus.
• Give every toggletip a visible close affordance. Escape and click-outside come free from the platform, but neither is discoverable by looking.
• Interactive targets inside the overlay — the close button above all — need at least 24×24px. Source: WCAG 2.5.8 Target Size (Minimum).
• Position the arrow so it plainly references its trigger, and leave enough room that the overlay neither covers the trigger nor crowds its neighbours.
• Use semantic colour tokens rather than fixed values, so the overlay adapts across schemes and surfaces.

For developers

Build both forms on the native HTML Popover API — the trigger carries popovertarget, the surface carries popover — and the browser does the hard parts for you: it promotes the surface to the top layer, light-dismisses on outside click and Escape, places the surface in the sequential tab order straight after its trigger, and returns focus to the trigger on close. Use popover="auto" for the toggletip and popover="hint" for the tooltip, so a tooltip can appear without dismissing an open toggletip.

Take the platform’s behaviour as the default and don’t fight it. In particular, do not move focus into the surface when it opens, and do not add a focus trap or a manual focus-return — the toggletip is non-modal, and the browser’s own sequence already lets someone Tab into the panel and back out. Anything focusable inside the panel simply takes its place in that sequence, so keep the set of controls small and its DOM order sensible.

A tooltip holds short, non-interactive text and never takes focus itself. If the content needs a link or a button, it is a toggletip — swap the form rather than making a tooltip focusable. Prefer a real element over the native title attribute, whose handling across screen readers, keyboards and touch is inconsistent. Keeping the surface in the DOM and toggling visibility tends to give more reliable assistive-technology support than mounting and unmounting it.

Two timing and placement details: delay a hover-triggered tooltip by roughly 300–500ms so it doesn’t fire on a passing pointer, and never auto-dismiss it. Both forms should flip and shift to stay inside the viewport rather than being clipped at an edge. Each element’s role, accessible name and state are in Labelling elements below; decorative icons stay out of the accessibility tree.

Keyboard interaction

Key	Action
Enter / Space	With the trigger focused, open or close the toggletip
Escape	Dismiss the open toggletip or tooltip; focus returns to the trigger
Tab / Shift + Tab	Move into the open toggletip and through its content, then on to the next / previous control — focus is not trapped

A tooltip appears when its trigger takes focus or hover and hides on blur, pointer-leave or Escape; it never receives focus. Every trigger and every control inside a toggletip must be operable from the keyboard alone. Source: WCAG 2.1.1 Keyboard.

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. The content slot is a placeholder, since consumer-slotted content carries its own component’s semantics.

Toggletip

The interactive form: a role="dialog" panel that may hold controls.

123

1. 1Toggletip trigger
2. 2Toggletip
3. 3Close button

Toggletip 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.

Toggletip

role="dialog" on the surface. 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

The read-only form: a role="tooltip" bubble of short text. Nothing inside takes focus, and the bubble takes no name of its own — its text content is what gets announced.

Battery range is measured on the WLTP cycle.

12

1. 1Tooltip trigger
2. 2Tooltip

Tooltip trigger

Which attribute you use depends on what the tooltip text is. When it supplements a control that already has a name, point aria-describedby at the tooltip’s id so the text is announced as a description. When the tooltip carries the control’s only name — the usual case for an icon-only button — use aria-labelledby instead; pairing aria-describedby with text that duplicates the button’s aria-label makes screen readers announce the same words twice.

Tooltip

role="tooltip" on the bubble — the same attribute the styleguide keys the compact chip styling off, so the look and the semantics cannot drift apart. It is not focusable and takes no name of its own.

Source: WCAG 4.1.2 Name, Role, Value.