ARIA: toolbar role

The toolbar role defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form.

A toolbar is a collection of commonly used controls, such as buttons or checkboxes, grouped together in a compact visual form. The toolbar role can be used to communicate the presence and purpose of such a grouping to screen reader users and can help reduce the number of tab stops for keyboard users. Only use the toolbar role to group 3 or more controls.

The toolbar is commonly a subset of functions found in a menubar as a way to reduce user effort. If you have more than one toolbar in a menubar, each toolbar requires a label; which you can include with aria-labelledby or aria-label.

When creating a toolbar, you need to implement focus management and keyboard interactions within the toolbar, handling when the same keyboard interactions is used both in the toolbar and in included native control. The Left Arrow and Right Arrow should be used to navigate between the controls withing a horizontal tool bar. The Up Arrow and Down Arrow should be used if the toolbar is vertical -- in which case you also want to include the aria-orientation="vertical" -- or, in a horizontal toolbar, can be reserved for operating controls, such as spin buttons that require vertical arrow keys to operate.

Avoid including controls whose operation requires arrow keys used for toolbar navigation. If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element.

If any of the otherwise interactive elements within the toolbar are temporarily disabled, consider letting them remain focusable so screen reader users can be made aware of their presence.

aria-orientation

Elements with the role toolbar have an implicit aria-orientation value of horizontal.

aria-labelledby / aria-label

If the toolbar has a visible label, reference it by ID with the aria-labelledby attribute. Otherwise, provide an aria-label. If there is more than one toolbar in a menu, naming is required.

Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar.

Tab and Shift + Tab

Move focus into and out of the toolbar. When focus moves into a toolbar:

• If focus is moving into the toolbar for the first time, focus is set on the first control that is not disabled.
• If the toolbar has previously contained focus, focus is optionally set on the control that last had focus. Otherwise, it is set on the first control that is not disabled.

Home (Optional)

Moves focus to first element.

End (Optional)

Moves focus to last element.

Horizontal toolbar

Elements with the role toolbar have an implicit aria-orientation value of horizontal. If the toolbar indeed has this orientation, the following keyboard interactions need to be implemented:

Left Arrow (For a horizontal toolbar (the default)

Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element.

Right Arrow (For a horizontal toolbar (the default)

Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element.

In toolbars with multiple rows of controls, allow the left and right arrows to wraps from row to row, leaving the option of reserving vertical arrow keys for operating controls, such as navigating among radios buttons, or incrementing/decrementing a numeric spinner.

Vertical toolbar

If the toolbar is vertical, ensure aria-orientation="vertical" is set, and the following keyboard interactions are implemented:

Down Arrow (For a horizontal toolbar (the default)

Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element.

Up Arrow (For a horizontal toolbar (the default)

Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element.

Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar. When tabbing into the toolbar, focus returns to the control that last had focus.

While the toolbar element itself does not receive focus, focus on movement into, out of, and within the toolbar has to be managed. On load, the first element in the tabbing sequence within the toolbar has tabindex="0" with tabindex="-1" set on all other focusable elements within the toolbar. Depending on the [keyboard interaction], the element receiving focus gets set to tabindex="0" and the element that just lost focus gets switched back to tabindex="-1". Set focus, element.focus(), on the element that has tabindex="0". This is called "roving tabindex". A benefit of using roving tabindex to manage focus is that the browser will scroll the newly focused element into view.

If the design calls for a specific element to be focused the next time the user moves focus into the toolbar with Tab or Shift + Tab, check if that target element has tabindex="0" when toolbar loses focus.

When the toolbar has focus within it, provide visual cues. When an element within the toolbar has focus, a visual cue must be included on both the toolbar itself - to help the toolbar supports directional navigation with the arrow keys - and the control that has focus. The CSS pseudoclasses of :focus and :focus-within can be used to target both elements.

Toolbar example from the W3C

Avoid including controls whose operation requires arrow keys used for toolbar navigation (right and left arrows, or top and bottom for vertical toolbars). If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element.

If any of the otherwise interactive elements within the toolbar are disabled, consider letting them remain focusable so screen reader users can be made aware of their presence.

• The CSS :focus pseudoclass
• The CSS :focus-within pseudoclass