Standards · ARIA

Role Document structure

toolbar

Marks a container as a toolbar — a grouped set of related controls (a formatting bar, a row of icon buttons). Reduces the tab-stop cost: a toolbar of 10 buttons becomes one tab-stop, with arrow keys to move between buttons.

When to use

When you have a row (or column) of three or more related controls — a text-editor formatting bar, the icon row above a chat input, photo-editing actions. The benefit is keyboard efficiency: instead of every button being its own tab-stop, the toolbar consumes one tab-stop and exposes its children via arrow keys.

A toolbar MUST have an accessible name (aria-label or aria-labelledby). The orientation defaults to horizontal; set aria-orientation="vertical" for a vertical bar.

Children are usually buttons (<button>), with role="separator" between logical groups. Toolbars CAN contain buttons, toggle buttons, links, menubuttons, and other small controls — but not whole forms or list widgets.

Keyboard + focus contract

Per the APG toolbar pattern:

  • Tab moves focus into the toolbar onto the first or last-focused control; Tab moves OUT.
  • Right/Left arrows (Up/Down if vertical) move between toolbar items.
  • Home / End jump to first / last.
  • Each individual button still activates on Enter or Space — its activation contract is unchanged by the toolbar role.

Use a roving tabindex: only one toolbar item has tabindex="0" at a time.

Common failures

  • All buttons in the toolbar have tabindex="0". Defeats the entire point — Tab steps through each button anyway.
  • Toolbar with no accessible name.
  • Toolbar buttons missing labels because the visual is an icon. Add aria-label to each.
  • Mixing toolbar with role="group" semantics. Pick one: toolbar implies arrow-key navigation, group does not.
  • role="toolbar" on a <nav> element. The roles conflict — use one or the other.

Example

<div role="toolbar" aria-label="Text formatting">
  <button type="button" tabindex="0"  aria-pressed="false" aria-label="Bold">B</button>
  <button type="button" tabindex="-1" aria-pressed="false" aria-label="Italic">I</button>
  <button type="button" tabindex="-1" aria-pressed="false" aria-label="Underline">U</button>
  <span role="separator" aria-orientation="vertical"></span>
  <button type="button" tabindex="-1" aria-label="Insert link">Link</button>
</div>