Skip to content

Toolbar

C-23 · Components · Navigation

All elements · Toolbar on the Components page

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

Copies the bun run a11y:approve command for Toolbar.

Toolbar

C-23WCAG 2.2 AA · Passed #416
Axis Values
data-bordered · data-density · data-sticky full · bottom / compact / sticky top
__group · __spacer · __title · .qf-divider[vertical] layout parts; overflow collapses tail groups into a Menu
Search toolbar

Toolbar: vertical and floating

C-23 Office

The PDF tool rail on narrow widths (data-orientation="vertical") and the annotation toolbar inside a popover (data-floating). Both are one tab stop with roving arrows (P-15).

Axis / element Values
data-orientation="vertical" a column of commands
data-floating a raised bar over the canvas
Vertical and floating

Guidance

When to use

  • Put the commands for one list, table or document in a bar above it: create, filter, view switch, refresh.
  • Head a pane or card with a __title and a few actions, using data-density="compact".
  • Keep a command bar on screen while content scrolls with data-sticky.
  • Stack tools in a column with data-orientation="vertical", such as the PDF tool rail on narrow widths.
  • Float a small set of commands over a canvas or selection with data-floating, such as the annotation bar.

When to consider something else

  • When the editor needs tabs of grouped commands with KeyTips, use Ribbon. See Ribbon.
  • When the commands apply to a text selection and appear next to it, use Mini toolbar. See MiniToolbar.
  • When there are only two or three related actions, use a Button group without toolbar semantics. See ButtonGroup.
  • When the actions belong to one row or item, put them in a Menu on that row. See Menu.

Usability

Do
  • Order groups by frequency: primary create action first, view and utility actions after the __spacer.
  • Separate groups with __group and a vertical .qf-divider.
  • Let tail groups collapse into a More Menu as the width shrinks, keeping the primary action visible.
  • Give every icon-only button an aria-label and a matching title or Tooltip.
  • Show pressed tools and view switches with aria-pressed, one pressed in a data-selection="single" group.
Don’t
  • Don't put more than one primary (filled) button in a toolbar.
  • Don't put form fields that need arrow keys in a roving toolbar without letting them keep their caret keys.
  • Don't wrap a toolbar onto two rows; collapse into the More menu instead.
  • Don't use role="toolbar" on a bar that holds only a title and one button.

Accessibility

Keyboard

Toolbar keyboard
Keys Action
Tab / Shift+Tab Enters and leaves the toolbar. In a roving toolbar (data-rove) the whole bar is one Tab stop.
Arrow Right / Arrow Left In a horizontal roving toolbar, moves to the next or previous control, wrapping at the ends.
Arrow Down / Arrow Up In a vertical toolbar (aria-orientation="vertical"), moves to the next or previous control.
Home / End Moves to the first or last control.
Ctrl+Arrow Right / Ctrl+Arrow Left In a horizontal roving toolbar, jumps to the first control of the next or previous group.
Enter or Space Activates the focused button or opens its menu.

Roles and names

  • A command bar uses role="toolbar" and an aria-label naming what it acts on, such as "PDF tools" or "Annotation".
  • A vertical toolbar sets aria-orientation="vertical".
  • Toggle tools carry aria-pressed; buttons that open a Menu carry aria-haspopup="menu" and aria-expanded.
  • The __title is plain text; if it titles a region, the binding should also use it as that region's label.
  • The search toolbar specimen leaves each button as its own Tab stop and has no aria-label; the binding must add the label and should add roving focus when it has more than a few controls.

Focus

  • In a roving toolbar only one control has tabindex="0"; it follows the last focused control, so Tab returns the user to where they were.
  • Arrow keys yield to text inputs inside the toolbar, which keep their caret keys.
  • When a control collapses into the More menu, focus must not be lost; move it to the More button.
  • Every control shows the shared focus ring; a sticky toolbar must not cover the focused element in the content below (2.4.11).

Other requirements

  • Small buttons are 2rem high, which meets 2.5.8; keep at least the gap the groups use between icon-only buttons.
  • Pressed state must show by more than color, such as the pressed background, and meet 3:1 against the bar (1.4.11).
  • At 320px width (1.4.10) the toolbar collapses into the More menu; nothing may become unreachable.
  • A floating toolbar must not hide the selection it acts on, and must close with Escape when it lives in a popover.

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.

Toolbar 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. (6 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. (5 items)

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

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

Latest updates

Toolbar 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