Open UI

Toolbar Elements (Explainer)

Table of Contents

Introduction

A toolbar is a common user interface pattern used to provide quick access to a group of commands, represented using controls such as press buttons, menus and other such controls.

This proposal introduces a new <toolbar> element. The <toolbar> will:

  • Represent a grouping of controls (e.g. buttons, select boxes, press buttons).
  • Provide the correct implicit ARIA role and keyboard interaction model out of the box.
  • Allow web developers to create consistent, accessible toolbars without re-implementing ARIA patterns.

Use cases:

  • The formatting toolbar in a document editor (bold, italic, underline, font family).
  • The main command toolbar in a drawing or photo editing app.
  • A simple toolbar with a search field and filter buttons in a catalogue.

New <toolbar> element

<toolbar>

  • Represents a group of controls.
  • Provides implicit role="toolbar".
  • Toolbars are displayed horizontally by default.
  • Provides correct keyboard navigation behaviour.

General questions

What should be the keyboard behavior?

This element will implicitly provide the same behaviour as a toolbar focusgroup.

  • It will contain a single tab-stop.
  • Arrow-keys can be used to navigate between focusable children.
  • Home keys can be used to jump to the beginning or end of the toolbar.
  • It should potentially support an orientation attribute. Issue 1201

How should we handle conflicting keyboard behavior from children?

There are many types of built-in HTML controls that already have existing keyboard behavior, we should ensure that these don’t lead to keyboard traps where users can’t escape.

Issue 1281 tracks a possible solution to these cases. It’s possible that there’s more specific interventions that we can make to avoid these issues in the first place.

How can users customize the UI of this toolbar element with CSS?

We propose this element should not support the CSS appearance property and just have a “base” appearance by default like the <dialog> element.

Questions

  • <toolbar> should display children horizontally, but support using CSS writing-mode.
    • Can have vertical case by:
      • Set CSS writing-mode: vertical-lr on the <toolbar>
      • Should this affect arrow-key directionality?
      • Should this also affect aria-orientation?
  • Does <toolbar> support separators?
    • If so, we should support <hr> for this.
  • Toolbars generally should be labelled, it is a MUST if there are multiple on a page. Should we support this via HTML, or still rely on aria?
    • Could use <legend> to do this?

Examples in code

Google Docs: Toolbar

A toolbar element as seen in Google Docs.
<toolbar aria-label="Main">
 <button id="undoButton" aria-label="Undo"><img src="..." alt=""></button>
 <button id="redoButton" aria-label="Redo"><img src="..." alt=""></button>
 <button id="printButton" aria-label="Print"><img src="..." alt=""></button>
 <input id="zoomSelect" list="zoom" aria-label="Zoom">
 ...
</toolbar>
<datalist id="zoom">
  <option>Fit</option>
  <option>50%</option>
  ...
</datalist>

<script>
undoButton.addEventListener("click", () => {
  undo();
});
</script>

Future enhancements

We envision more advanced capabilities in the future that could enhance the usability of the toolbar designed in this explainer, but that are not necessarily in scope for our initial proposal.

One such capability is keyboard shortcuts to invoke controls within the toolbar; see https://github.com/openui/open-ui/issues/1225. We envision that this could be provided by a more advanced version of the accesskey primitive, that would provide customizable key commands that apply outside the scope of our proposal.

Reading List

ARIA guidelines

Relevant ARIA issues

APG pattern recommendations (note these are not guidelines)

Blog posts from accessibility community

  • Fill as and when they’re discovered

Blog posts for Design System

Issues / Discussions

This section links to all of the relevant discussions and issues related to toolbar:

OpenUI