# Toolbar

A named row of controls that act on the view under it, kept on one line by moving controls behind More in a declared order.

* Kind: component
* Page: https://design.werklist.com/components/toolbar
* Version: 2.1.2

## When to use it

* Board toolbars: views, search, filters, the add action.
* Formatting bars in editors and composers.
* Selection bars that act on chosen rows.

## When not to use it

* Navigation between places: header, side navigation, tabs.
* Rarely used settings in the row: put them behind More or in settings.
* A title or a hero above the toolbar or inside it: a view starts at its toolbar.

## Rules

* Each toolbar declares the order in which its controls give way. The view switch, the search and the add action never give way.
* A control comes back once there is clear room for it.
* A toolbar responds to the room it has, so opening a side panel can move controls behind More.
* A toolbar does not wrap and does not scroll sideways. A formatting toolbar may wrap below 640 px.
* Destructive actions in their own group.

## Anatomy

* Container: role toolbar with aria-label. No fill of its own. It stands on the frame of a board (--surface-1) or the well of a composer.
* Control: Labeled controls are small buttons, 36 px high. Icon only controls are small icon buttons, 32 px, centered on the row. Both are drawn at 44 px on coarse pointers. (--radius-lg)
* Label and icon: 13 px, weight 500. Icon 16 px, 8 px before the label.
* Gap: 8 px between controls, 6 px below 640 px (--space-2)
* Groups: At most three, in order: leading (the view switch), tools, trailing (the one add action, right after the tools). The room left over stays at the end of the row.
* Divider: 1 by 20 px, only between groups of icon only controls, aria-hidden (--border)
* Search field: Outside the group of arrow keys, with its own Tab stop. At least 200 px, 320 px when there is room.
* More: 36 px, the More icon and the count. The count is aria-hidden and joins the name: More, 2.

## States

* Rest, board: Tools: quiet buttons on the --glass-fill-hover fill, in --text-muted ink (--glass-fill-hover, --text-muted)
* Rest, formatting: No fill, --text-muted ink (--text-muted)
* Hover: --text ink. In a formatting bar the tool also takes --glass-fill-hover. Only on a pointer that can hover. (--glass-fill-hover, --text)
* Pressed, board tool: aria-pressed true: --brand-blue at 15 percent as the fill, --brand-ink as the ink (--brand-blue, --brand-ink)
* View in use, board: aria-pressed true in the leading group: --surface-control fill, --text ink (--surface-control, --text)
* Pressed, formatting: aria-pressed true: --seg-selected fill, --text ink (--seg-selected, --text)
* Focus: 2 px ring, 2 px offset (--focus-ring)
* Unavailable: aria-disabled true, opacity 0.5. It stays in place and in the group.
* Behind More: The control waits in the row that More opens and keeps its state.

## Keyboard

* Tab: Enters the toolbar at the last used control. The next Tab leaves it.
* Left arrow, Right arrow: Previous or next control
* Home, End: First or last control
* Enter, Space: Uses the control
* Down arrow: Opens a menu control

## Accessibility

* role toolbar with aria-label naming what it acts on.
* The controls share one Tab stop and the arrow keys move between them. The search field has a Tab stop of its own.
* Icon only controls: aria-label and a tooltip with the same words.
* Toggles: aria-pressed.
* More: aria-expanded and a name that includes the count.

## Content

* Labels are short verbs or nouns in sentence case, no end punctuation: Filter, Group by, Export, Add candidate.
* The add action names what it adds: Add candidate, Add task.

## Tokens

* --radius-lg
* --space-2
* --border
* --glass-fill-hover
* --text
* --text-muted
* --brand-ink
* --surface-control
* --seg-selected
* --brand-blue
* --focus-ring