Skip to content

Tooltip

C-05 · Components · Overlays

All elements · Tooltip on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Tooltip.

Tooltip

C-05WCAG 2.2 AA · Passed #398

Hover/focus description with a 300ms enter delay. Lives in a Layer[kind=tooltip]; the static host shown here is CSS-only.

Axis Values
data-placement · data-arrow top (default) · bottom · … / arrow
data-variant dark (default) · light
.qf-tooltip__header bold title line
Hover the buttons
Refresh the results Last indexed2 minutes ago by Jane Doe Light tooltip on a paper surface

Tooltip: rich

C-05 Office

The "super tooltip" of ribbon commands: title, shortcut, a one-paragraph description and, on a disabled command, the reason it is unavailable.

Axis / element Values
data-variant="rich" on .qf-tooltip
__header · __shortcut · __description · __reason parts
Enabled and disabled

Guidance

When to use

  • Use a tooltip to name an icon-only button or show its keyboard shortcut.
  • Use a tooltip for a short, extra description that the user can do without, such as "Last indexed 2 minutes ago".
  • Use the rich tooltip (data-variant="rich") on ribbon commands to show the title, shortcut, a one-paragraph description and, when disabled, the reason.
  • Use the light variant on dark or busy surfaces where the dark tooltip blends in.

When to consider something else

  • If the content has links, buttons, inputs or must be read in full, use a popover. See Popover.
  • If the information is needed to complete a task, show it as field helper text instead. See Field.
  • If the message reports the result of an action, use a toast. See Toast.

Usability

Do
  • Keep it to one short line, or the rich layout's fixed parts.
  • Match the tooltip text to the button's accessible name for icon-only buttons.
  • Explain why a command is unavailable in the rich tooltip's __reason line.
  • Keep the 300ms enter delay so tooltips do not flash while the pointer crosses a toolbar.
Don’t
  • Don't put interactive content in a tooltip; it cannot be reached.
  • Don't put essential instructions or error text in a tooltip.
  • Don't add a tooltip that repeats a visible label word for word.

Accessibility

Keyboard

Tooltip keyboard
Keys Action
Tab Focusing the trigger shows the tooltip after the delay.
Escape Hides the tooltip without moving focus; it shows again after focus or the pointer leaves and returns.

Roles and names

  • The tooltip element has role="tooltip".
  • The binding must link the trigger to the tooltip with aria-describedby, or use it as the aria-label source for an icon-only button; the static host does not set either.
  • The rich tooltip's shortcut belongs in aria-keyshortcuts on the command as well.
  • Office commands set title today; the React binding should replace it with the tooltip so the text is not read twice.

Focus

  • The tooltip never takes focus; focus stays on the trigger.
  • A tooltip on a native disabled button never shows for keyboard users; use aria-disabled="true" on the command so the reason can be reached.

Other requirements

  • 1.4.13 Content on Hover or Focus: the tooltip is dismissible with Escape, stays while the pointer moves onto it, and stays until hover or focus ends.
  • Text must reach 4.5:1 (1.4.3) in every theme; the dark theme swaps to a light fill with a border for this reason.
  • The fade respects prefers-reduced-motion (2.3.3).
  • Tooltips do not appear on touch; any information they carry must also be available another way (2.5.1, 1.3.3).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Tooltip test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (2 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- tooltip --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Tooltip package
Source css/classic/components/overlays.css
Specimens also use Box · Button · Card · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

Tooltip latest updates
Date Version Breaking Description
2026-10-02 0.1 No Extend Tooltip, Menu, Select, Tabs and Toolbar for office surfaces

All release notes