Source: https://monarchui.dev/components/toolbar/

Patterns · Actions

# Toolbar

Search, controls and trailing actions above a list, with arrow-key focus movement.

@rookcom/monarch-react

Pattern

## List tools

## Usage examples

The example at the top of the page is the only one for this component.

## Purpose

A `role="toolbar"` row for the controls above a list or board: a search slot, grouped controls, trailing controls and an optional filters row underneath.

### Use when

- Several related controls act on the same list or view (search, filter, sort, export).

### Avoid when

- A form with labelled fields: use Field or SettingsSection.
- One or two buttons: place them directly, no toolbar role needed.

## Design principles

- One Tab stop region with arrow keys inside, as the ARIA toolbar pattern expects.
- Text inputs keep their own Left/Right keys so typing is never hijacked.
- Trailing controls (`end`) align to the inline end.

## API reference

```tsx
import { Toolbar, ToolbarGroup } from '@rookcom/monarch-react';
```

| Export | Kind | Rendering | Root class |
| --- | --- | --- | --- |
| `Toolbar` | component | client | `.mn-toolbar-wrap` |
| `ToolbarGroup` | component | client | `.mn-toolbar-wrap` |

Native div attributes go to the inner `role="toolbar"` element; `className` goes to the outer `.mn-toolbar-wrap`.

Your `onKeyDown` runs first; calling `preventDefault()` skips the built-in arrow handling.

ToolbarGroup renders a `role="group"` div for visual grouping.

Generated from the TypeScript declarations of `packages/react/src/patterns/actions/toolbar`.

## Properties

### `Toolbar`

`role="toolbar"` with roving focus: Tab enters the toolbar, Left/Right move between controls, Home/End jump. Text inputs keep their own arrow keys.

| Prop | Type | Description |
| --- | --- | --- |
| `label` required | `string` | Accessible name, e.g. "Ticket list tools". Required by the toolbar role. |
| `children` | `ReactNode` |  |
| `className` | `string` |  |
| `end` | `ReactNode` | Controls on the trailing edge (view switch, density, export). |
| `filters` | `ReactNode` | Filter chips row rendered under the toolbar. |
| `id` | `string` |  |
| `search` | `ReactNode` | Search or filter input area on the leading edge. |

### `ToolbarGroup`

Visual grouping inside a Toolbar.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `ReactNode` |  |
| `className` | `string` |  |
| `id` | `string` |  |

## Variants

| Prop | Values | Description |
| --- | --- | --- |
| `search / children / end / filters` | `'omitted'``'provided'` | Each slot renders its wrapper only when provided; `filters` renders below the toolbar row. |

## States

| State | Exposed as | Behaviour |
| --- | --- | --- |
| Static | – | No state of its own; controls in the slots own their states. |

## Interaction behaviour

- Arrow and Home/End keys move focus among focusable elements whose nearest toolbar is this one (nested toolbars are skipped).
- Movement stops at the ends; it does not wrap.
- Left/Right are ignored while a text input has focus; checkbox, radio and button inputs still move.
- Focus is not roving-tabindex: every control stays in the Tab order.

## Keyboard support

| Keys | Action |
| --- | --- |
| Arrow Right / Arrow Left | Next / previous control (not inside text inputs). |
| Home / End | First / last control, including from a text input. |
| Tab | Moves through the controls in document order. |

## Accessibility

Role

toolbar

Accessible name

label

(required), used as

aria-label

.

- The type requires `label`, so the toolbar always has an accessible name.

## Responsive behaviour

- The row wraps; the search slot flexes between 10rem and 24rem.
- Trailing controls use `margin-inline-start: auto` and wrap under when space runs out.

## Theme support

- Layout only; colours come from the controls placed inside.

## Do and don't

### Do

- Name the toolbar after what it controls ("Ticket list tools").
- Put active filters in `filters`.

### Don't

- Do not nest a toolbar inside another toolbar.
- Do not put unrelated page actions in a list toolbar.

## Related components

- [FilterBar](https://monarchui.dev/components/filter-bar/): Active filters, usually in the `filters` slot.
- [SearchInput](https://monarchui.dev/components/search-input/): Planned search control for the `search` slot (wave 1).
- [PageHeader](https://monarchui.dev/components/page-header/): Page-wide actions sit above the toolbar.
- [DataTable](https://monarchui.dev/components/data-table/): The list the toolbar usually controls.

## Dependencies

| Kind | Depends on |
| --- | --- |
| npm packages | `react` |
| Monarch components | None |

## Testing coverage

- Has role toolbar with the given label.
- Arrow Right, End and Home move focus; Left inside a text input stays in the input.
- ToolbarGroup renders a labelled group.

| Check | Covered |
| --- | --- |
| Axe in jsdom | Yes |
| Server rendering | Yes |
| Browser suites | None yet |

Tests: `packages/react/src/patterns/actions/toolbar`

## All example code

### List tools

```tsx
import { Button, Input, Toolbar, ToolbarGroup } from '@rookcom/monarch-react';

<Toolbar
  label="Task list tools"
  search={<Input aria-label="Search tasks" placeholder="Search tasks" />}
  end={<Button>Export</Button>}
>
  <ToolbarGroup aria-label="View">
    <Button>Board</Button>
    <Button>List</Button>
  </ToolbarGroup>
</Toolbar>
```