UX Patterns Guide
UI + UX Task And Workflow Patterns standard

Toolbar

Use a labelled toolbar for a cohesive set of view-scoped controls, define command groups and overflow, expose current selection and pressed or disabled states, implement efficient keyboard movement, and route unrelated navigation or primary workflow actions to clearer patterns.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A view, editor, canvas, media surface, table, or selection needs repeated related commands close to the work area.
  • Users benefit from visible command availability, toggle state, and quick keyboard movement.
  • The command set has enough structure to justify grouping, separators, overflow, or compact controls.

Avoid when

  • There are only one or two actions that should be ordinary buttons.
  • The controls navigate between app sections or pages.
  • The command set is broad enough to require search and ranking.
  • The commands affect different scopes and would make object ownership unclear.
  • The implementation cannot provide names, focus behavior, state, and overflow affordances.

Problem it prevents

Products often need repeated commands near a view or selection, but loose action rows become crowded, unlabeled, hard to navigate by keyboard, and ambiguous about what object or state they affect.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Toolbar in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

A document, canvas, map, table, list, media viewer, or selected object has several frequent commands that users apply repeatedly.

Pattern promise

Use a labelled toolbar for a cohesive set of view-scoped controls, define command groups and overflow, expose current selection and pressed or disabled states, implement efficient keyboard movement, and route unrelated navigation or primary workflow actions to clearer patterns.

Required state

Default toolbar with label, visible scope, grouped controls, and focusable entry point.

Recovery path

The toolbar has no accessible name, so screen reader users hear a generic group of buttons with no purpose.

Access contract

Use role toolbar only for a cohesive group of controls whose grouping helps users, and give each toolbar a clear accessible name.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A document editor toolbar labels the current document, groups Undo and Redo, formatting toggles, alignment controls, Insert link, and More, with Bold shown pressed for the selected text.
  • A data-table toolbar appears only when rows are selected, shows 3 selected, enables Export and Archive, disables Merge with a reason, and keeps More actions secondary.
  • A keyboard user tabs once into the editor toolbar, uses Right Arrow to move from Bold to Italic, presses Space to toggle Italic, and focus remains in the toolbar while selected text stays selected.
  • A user selects three files, sees the toolbar switch to selection scope, exports them, then clears selection and the toolbar disables selection-only commands.
Weak implementation

Vague, hidden, hard to recover from

  • A toolbar contains Back, Save, Delete, Pricing, Account, Filter, and Help with no shared scope or grouping.
  • A row of icon-only buttons has no labels, no pressed state for active formatting, no overflow explanation, and no disabled reason.
  • A keyboard user must tab through twenty toolbar buttons before reaching the editor body.
  • A user clicks Archive in a toolbar but cannot tell whether it affects the selected row, the whole folder, or the current page.
UI guidance
  • Render a toolbar as a labelled command region attached to the view, editor, canvas, table, or selected object it controls, with grouped buttons, toggle buttons, menu buttons, separators, compact inputs, overflow, and current state visible where relevant.
  • Keep toolbar controls compact but not mysterious: use predictable order, stable grouping, visible focus, enabled and disabled states, pressed toggle state, current selection summary, and precise accessible names for icon-only controls.
UX guidance
  • Use a toolbar when users repeatedly apply related commands to the same view or selection and need fast visible access without opening a modal command surface.
  • Make scope and keyboard efficiency explicit: users should know what object the toolbar affects, move among controls predictably, activate commands without losing selection, and find overflow without hunting for primary work.
Implementation contract

What the implementation must handle

States

  • Default toolbar with label, visible scope, grouped controls, and focusable entry point.
  • Keyboard focus inside the toolbar with current roving item or active control indicated.
  • Arrow-key movement among toolbar controls.
  • Pressed or selected toggle state for stateful commands such as Bold, Filters on, or Preview mode.

Interaction

  • The toolbar has a clear accessible name and visual scope tied to the current view, selected objects, or editor surface.
  • Controls inside the toolbar share one command context; unrelated navigation and page-level settings stay outside.
  • Tab reaches the toolbar in a predictable place, and implementations using composite toolbar behavior let arrow keys move between controls.
  • Home and End move to first and last toolbar controls when supported by the implementation.

Accessibility

  • Use role toolbar only for a cohesive group of controls whose grouping helps users, and give each toolbar a clear accessible name.
  • Set aria-orientation when the toolbar is vertical; horizontal is the default orientation.
  • Implement roving tabindex or equivalent focus management when the toolbar is one tab stop.
  • Use Arrow Left and Arrow Right for horizontal toolbar movement, with optional vertical arrow duplication only when it does not conflict with child controls.

Review

  • What surface or selected object does this toolbar control?
  • Do all controls share that scope, or are navigation and unrelated commands mixed in?
  • Can keyboard users enter once, move between controls efficiently, activate a command, and keep their selection?
  • Which controls are stateful, disabled, destructive, or overflowed, and how are those states exposed?
Evidence trail

Source-backed claims behind this guidance

WAI-ARIA APG Toolbar Pattern

W3C WAI - checked

APG defines toolbar grouping, one-tab-stop focus management, arrow-key navigation, orientation, labelling, and disabled control discoverability.

MDN ARIA toolbar role

MDN Web Docs - checked

MDN documents toolbar role semantics, focus management, horizontal and vertical arrow behavior, multiple-toolbar labelling, and nested-control key conflicts.

Fluent UI Toolbar

Microsoft Learn - checked

Fluent documents toolbar as a W3C-aligned grouped command component for buttons, menu buttons, and checkboxes.

Full agent/debug reference

Problem Context

  • A document, canvas, map, table, list, media viewer, or selected object has several frequent commands that users apply repeatedly.
  • The commands share one scope and can remain visible without interrupting the work surface.
  • Some commands are compact, stateful, grouped, or lower priority enough to need separators, toggles, menus, or overflow.
  • Keyboard users need to move through the command set efficiently without leaving the work context.

Selection Rules

  • Choose toolbar when a persistent view-scoped command surface groups several related controls for repeated use.
  • Use a button group when there are only a few visible peer actions for one workflow moment and ordinary tab order is sufficient.
  • Use a menu button when secondary commands can stay hidden behind one named trigger.
  • Use a command palette when commands are broad, searchable, shortcut-driven, or cross-product rather than scoped to the current view.
  • Use header, global navigation, side navigation, tabs, or bottom navigation when controls move between destinations instead of applying commands.
  • Do not put unrelated actions into one toolbar just because they share horizontal space.
  • Do not rely on tooltips as the only names for icon-only toolbar controls.
  • Keep primary submit, destructive review, and multi-step decisions outside overflow unless the toolbar is explicitly the correct command surface.
  • Define overflow priority before responsive collapse so essential controls remain available and secondary controls move predictably.
  • Use toolbar role and composite keyboard behavior only when the implementation provides arrow-key focus movement and predictable nested-control behavior.

Required States

  • Default toolbar with label, visible scope, grouped controls, and focusable entry point.
  • Keyboard focus inside the toolbar with current roving item or active control indicated.
  • Arrow-key movement among toolbar controls.
  • Pressed or selected toggle state for stateful commands such as Bold, Filters on, or Preview mode.
  • Disabled command state with visible reason or unavailable target.
  • Selection-scoped state showing selected object count and enabled contextual commands.
  • Overflow state when commands do not fit or are lower priority.
  • Nested menu button or compact input state inside the toolbar.
  • Command activated state with status feedback and focus preserved.
  • Responsive narrow viewport state with stable priority and reachable overflow.

Interaction Contract

  • The toolbar has a clear accessible name and visual scope tied to the current view, selected objects, or editor surface.
  • Controls inside the toolbar share one command context; unrelated navigation and page-level settings stay outside.
  • Tab reaches the toolbar in a predictable place, and implementations using composite toolbar behavior let arrow keys move between controls.
  • Home and End move to first and last toolbar controls when supported by the implementation.
  • Enter or Space activates the focused command, toggles stateful buttons, or opens a nested menu button according to the control role.
  • Activation preserves the user's object selection and focus unless the command intentionally opens a dialog, route, or confirmation flow.
  • Disabled controls communicate why they are unavailable when the reason is not obvious from selection or context.
  • Overflow retains command labels, grouping, and object scope rather than becoming an unnamed dumping ground.
  • Nested controls define whether arrow keys move within the control or across toolbar items, avoiding conflicting behavior.

Implementation Checklist

  • Inventory the commands and remove actions that do not share the toolbar's current view or selection scope.
  • Name the toolbar by the surface it controls, such as Text formatting, Map tools, Selected rows, or File preview actions.
  • Group controls by task, add separators where groups change, and order commands by frequency and risk.
  • Define which commands are visible, which move to overflow, and which belong in a menu, dialog, footer, or command palette.
  • Implement native buttons, toggle buttons, menu buttons, inputs, and labels with synchronized accessible names and states.
  • Choose ordinary tab order or composite toolbar keyboard behavior deliberately; if using toolbar role, implement arrow movement and orientation.
  • Keep disabled reasons, selected object count, pressed state, command result, and overflow status available to assistive technology.
  • Test keyboard, screen reader, high zoom, touch target size, mobile overflow, localization, forced colors, and nested widget key conflicts.

Common Generated-UI Mistakes

  • Labelling any horizontal button row as a toolbar without shared scope or keyboard behavior.
  • Using a toolbar for primary app navigation or unrelated destinations.
  • Packing rare, destructive, and primary submit actions into one dense strip.
  • Using icon-only buttons whose names exist only in hover tooltips.
  • Forgetting pressed state for toggles such as Bold, Filter on, or Preview.
  • Leaving selection-only commands enabled when nothing is selected.
  • Putting form fields, tables, or long explanations in toolbar overflow.
  • Letting responsive collapse hide important commands behind an unnamed More icon.

Critique Questions

  • What surface or selected object does this toolbar control?
  • Do all controls share that scope, or are navigation and unrelated commands mixed in?
  • Can keyboard users enter once, move between controls efficiently, activate a command, and keep their selection?
  • Which controls are stateful, disabled, destructive, or overflowed, and how are those states exposed?
  • Would a button group, menu button, command palette, header, or navigation pattern better match the user's job?
Accessibility
  • Use role toolbar only for a cohesive group of controls whose grouping helps users, and give each toolbar a clear accessible name.
  • Set aria-orientation when the toolbar is vertical; horizontal is the default orientation.
  • Implement roving tabindex or equivalent focus management when the toolbar is one tab stop.
  • Use Arrow Left and Arrow Right for horizontal toolbar movement, with optional vertical arrow duplication only when it does not conflict with child controls.
  • Keep disabled controls focusable only when users need to discover their presence or blocked reason; otherwise ensure the reason is available nearby.
  • Give icon-only controls precise accessible names and keep tooltips supplemental.
  • Expose toggle state with aria-pressed or native selected semantics where appropriate.
  • Ensure nested menu buttons, spin buttons, sliders, text inputs, and selects have keyboard behavior that does not fight toolbar navigation.
Keyboard Behavior
  • Tab moves focus to the toolbar or first toolbar control according to the chosen implementation.
  • Right Arrow and Left Arrow move between controls in a horizontal toolbar.
  • Down Arrow and Up Arrow may move in a vertical toolbar or may operate nested controls when those controls own vertical arrows.
  • Home and End move to the first and last toolbar control when implemented.
  • Enter or Space activates command buttons and toggles toggle buttons.
  • Menu buttons inside the toolbar open their menus and then follow menu-button keyboard behavior.
  • Escape closes nested menus or dialogs and returns focus to the invoking toolbar control when appropriate.
  • After a command runs, focus remains on the control or returns to it after any required confirmation.
Variants
  • Editor formatting toolbar
  • Selection toolbar
  • Table action toolbar
  • Canvas tool strip
  • Media control toolbar
  • Contextual toolbar
  • Floating toolbar
  • Bottom toolbar
  • Overflow toolbar
  • Customizable toolbar

Verification

Source trail checked:

Saved items