Skip to content

KeyTip

C-31 · Components · Editor (Office)

All elements · KeyTip on the Components page

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

Copies the bun run a11y:approve command for KeyTip.

KeyTip

C-31 OfficeWCAG 2.2 AA · Passed

An access-key badge at the bottom centre of its target, shown by the KeyTips primitive (P-16) on Alt+Windows or Ctrl+Option. Badges are aria-hidden; the same keys are on the control as aria-keyshortcuts.

Axis / element Values
.qf-keytip one or two letters
data-state="dimmed" does not match the keys typed so far
data-placement="start" aligned to the start of the target
Layer 1 on the tab row, after typing "H"

Guidance

When to use

  • Use it to show access keys on ribbon tabs, the File button and panel commands while the KeyTips layer is on.
  • Use one or two letters per target, unique within the layer that is showing.
  • Use data-state="dimmed" to fade badges that no longer match the keys typed so far.
  • Use data-placement="start" when a centered badge would cover a neighbor or clip at an edge.

When to consider something else

  • When the user needs to learn a command's regular shortcut, such as Ctrl+B, show it in the Tooltip instead of a KeyTip. See Tooltip.
  • When a short-lived hint must be read by screen readers, use a Toast or a live region; KeyTips are hidden from assistive technology. See Toast.

Usability

Do
  • Keep letters stable across sessions so users can build muscle memory.
  • Pick letters from the label where possible (H for Home, N for Insert).
  • Clear all badges on Escape from the first layer, on a pointer press, or after a command runs.
  • Draw badges only for visible, enabled targets.
Don’t
  • Don't use KeyTips as the only keyboard path; every target must also be reachable by Tab and arrow keys.
  • Don't reuse a letter within one layer.
  • Don't place badges outside the editor's .qf-office scope.

Accessibility

Keyboard

KeyTip keyboard
Keys Action
Alt+Windows (Ctrl+Option on macOS) Shows layer 1: badges on the File button and the ribbon tabs.
A letter on layer 1 Activates the matching tab, focuses it, and shows layer 2 on that tab's panel.
A letter on layer 2 Clears the badges, focuses the matching control and activates it.
Escape On layer 2, returns to layer 1; on layer 1, clears all badges.

Roles and names

  • Each .qf-keytip carries aria-hidden="true"; the badge is visual only.
  • The target exposes the same keys with aria-keyshortcuts (for example Alt+Meta+H) so assistive technology can announce them.
  • The badge is a child of its target and has no role.

Focus

  • Showing badges does not move focus.
  • Choosing a target moves focus to it; on layer 2 the command also runs.

Other requirements

  • Badges have pointer-events: none, so they never block clicks on their targets.
  • Dimmed badges use reduced opacity; they are supplementary, but the active ones must keep 4.5:1 text contrast (1.4.3).
  • In forced colors the badge keeps a system-color border so it stays visible.
  • The modifier chord is not a single-character shortcut, so 2.1.4 Character Key Shortcuts does not apply to the letters, which only work while the layer is open.

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.

KeyTip 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. (4 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. (3 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- keytip --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.

KeyTip package
Source css/classic/components/commands.css
Specimens also use Box · Card · Chip · Ribbon · Table · Text · Toolbar
Sprites —
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes