Skip to content

Ribbon

C-33 · Components · Editor (Office)

All elements · Ribbon on the Components page

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

Copies the bun run a11y:approve command for Ribbon.

Ribbon

C-33 OfficeWCAG 2.2 AA · Passed

One DOM for both modes (spec §1.2): every control is written once with data-priority and its label; data-mode picks Compact (the default: one row, labels visually hidden, priorities 3–4 in the ⋯ menu) or Full (three small rows or a large button per group, group labels, launchers). As the width shrinks, both modes shed labels, then move controls into the ⋯ menu by priority (last group first), then fold whole groups into dropdowns; groups never overlap or clip, and horizontal scrolling is only the last resort (P-20). The tab row takes the app accent and the panel stays flat.

Axis / element Values
data-mode compact (default) · full
data-state collapsed (show tabs only) · popup
__bar · __file · __tabs · __tab · __contextual · __end · __search the tab row
__panel · __toolbar · __group · __group-body · __group-label · __launcher the panel (role=tabpanel → role=toolbar → role=group)
__stack · __rows · __row · __sep Full layout of small controls
__more · __display · __collapsed-group · __placeholder overflow, display options, folded group, unbuilt tab
data-ribbon-only compact · full (a gallery in Full is a value button in Compact)
Compact (default)
Full

Guidance

When to use

  • Use it as the command surface of the QEditor document, spreadsheet, presentation and PDF editors.
  • Use Compact (the default) to give the canvas more room; use Full when users want labels, group names and launchers.
  • Use contextual tabs (__contextual) for commands that apply only to the selected object, such as a table or a chart.
  • Write each control once with data-priority and its label so both modes and every width come from one DOM.

When to consider something else

  • For a record, list or inbox view outside the editors, use a Toolbar; the ribbon is only for document editing. See Toolbar.
  • When a few commands must follow a text selection, use the Mini toolbar in addition to the ribbon. See MiniToolbar.
  • For switching between content views that are not command sets, use Tabs. See Tabs.

Usability

Do
  • Order groups by frequency, and give low-use controls priority 3 or 4 so they move into the ⋯ menu first.
  • Let the ribbon shed labels, then move controls into __more by priority, then fold groups; scroll only as the last resort.
  • Give each group a label and, in Full, a __launcher for its dialog.
  • Use Fluent UI System Icons, Regular style at size 20, from sprites/office-icons.svg; no Tabler glyphs and no Filled styles inside the ribbon (README, Icons).
  • Show state with aria-pressed and the pressed background, never with a glyph swap.
Don’t
  • Don't let groups overlap or clip at any width.
  • Don't put a command only in the ⋯ menu at full width; overflow is for narrow widths and low priority.
  • Don't duplicate controls to build the two modes; one DOM serves both.
  • Don't use Microsoft product names or logos in tabs or labels.

Accessibility

Keyboard

Ribbon keyboard
Keys Action
Tab Moves to the active tab, then to the panel toolbar's single stop, then out of the ribbon.
Arrow Left / Arrow Right on the tabs Moves to and activates the previous or next tab (automatic activation).
Arrow Down or Enter on a tab Moves focus into the tab's panel at its current stop.
Arrow Left / Arrow Right in the panel Moves between controls; text inputs keep their caret keys.
Ctrl+Arrow Left / Ctrl+Arrow Right Jumps to the first control of the previous or next group.
Home / End Moves to the first or last tab or control.
Escape in the panel Returns focus to the active tab.
Alt+Windows (Ctrl+Option on macOS) Shows KeyTips for the tabs, then for the panel's commands.

Roles and names

  • The ribbon is a <section> with an aria-label; __tabs is role="tablist" and each __tab is role="tab" with aria-selected and aria-controls.
  • __panel is role="tabpanel" labeled by its tab; inside it __toolbar is role="toolbar" and each __group is role="group" labeled by __group-label.
  • Menu buttons, __more and folded groups carry aria-haspopup and aria-expanded; launchers carry aria-haspopup="dialog".
  • Commands with KeyTips expose them with aria-keyshortcuts.

Focus

  • The tablist and each panel toolbar have one tab stop each (roving tabindex); the last focused control keeps its stop.
  • Menus and popups return focus to their trigger on close.
  • Controls moved into __more stay reachable by keyboard from that menu.

Other requirements

  • The ribbon must reflow at 320 CSS px by collapsing groups rather than requiring two-dimensional scrolling (1.4.10).
  • Small commands are 1.5rem (24px), which meets 2.5.8; keep that size when labels are shed.
  • Compact mode hides labels visually only; every icon-only control keeps an accessible name (4.1.2).
  • Check focus rings and pressed states against the accent tab row and the flat panel (1.4.11).

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.

Ribbon 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. (8 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 -- ribbon --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.

Ribbon package
Source css/classic/components/ribbon.css
css/classic/composites/office-ppt-ribbon.css
css/classic/composites/office-word.css
Specimens also use Box · Button · Card · Chip · Icon · Select · SplitButton · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

Ribbon latest updates
Date Version Breaking Description
2026-10-02 0.1 No One shared ribbon field (.qf-ribbon__field/__fields) and check box (.qf-ribbon__check) in ribbon.css, and the phone command bar and sheet (.qf-office-app__commandbar/__sheet) in office-shell.css, replacing the Document and Presentation copies; office:shared-pieces check (QF-10740)
2026-10-02 0.1 No Compact kept labels size to their content on one line; .qf-ribbon__check for ribbon check boxes replaces the Spreadsheet inline styles; ribbon-fit and office:ribbon-check assertions (QF-10740)

All release notes