# Toolbar

> Groups related controls into one tab stop with arrow-key navigation.

Category: Actions · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/toolbar

Use Toolbar for clusters of frequently used controls that act on the same object, such as text formatting in the signature editor or bulk actions above a table. The whole toolbar is a single tab stop, and the arrow keys move between controls, which keeps keyboard navigation efficient on dense screens.

## Import

```tsx
import { Toolbar, ToolbarGroup, ToolbarSeparator, ToolbarSpacer } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Formatting toolbar

```tsx
import * as React from 'react';
import { Icon, IconButton, Toolbar, ToolbarGroup, ToolbarSeparator, ToggleButton } from '@bindshq/stance-react';

export function Basic() {
  const [bold, setBold] = React.useState(true);
  const [italic, setItalic] = React.useState(false);
  return (
    <Toolbar aria-label="Signature text formatting">
      <ToolbarGroup aria-label="Style">
        <ToggleButton size="sm" pressed={bold} onPressedChange={setBold} aria-label="Bold">
          <strong>B</strong>
        </ToggleButton>
        <ToggleButton size="sm" pressed={italic} onPressedChange={setItalic} aria-label="Italic">
          <em>I</em>
        </ToggleButton>
      </ToolbarGroup>
      <ToolbarSeparator />
      <ToolbarGroup aria-label="Insert">
        <IconButton size="sm" variant="ghost" label="Insert link" icon={<Icon name="link" />} />
        <IconButton size="sm" variant="ghost" label="Insert image" icon={<Icon name="image" />} />
      </ToolbarGroup>
      <ToolbarSeparator />
      <IconButton size="sm" variant="ghost" label="Undo" icon={<Icon name="refresh" />} disabled />
    </Toolbar>
  );
}
```

### With a field and trailing actions

Text fields keep Left and Right for the caret; Up and Down never apply in a horizontal toolbar.

```tsx
import { Icon, Toolbar, ToolbarSeparator, ToolbarSpacer, Button } from '@bindshq/stance-react';

export function WithInputs() {
  return (
    <Toolbar aria-label="Template actions">
      <input
        aria-label="Template name"
        defaultValue="Sales team signature"
        style={{
          height: 32,
          padding: '0 8px',
          border: '1px solid var(--st-color-border-control)',
          borderRadius: 6,
          background: 'var(--st-color-bg-surface)',
          color: 'inherit',
        }}
      />
      <ToolbarSeparator />
      <Button size="sm" variant="ghost" leadingIcon={<Icon name="eye" />}>
        Preview
      </Button>
      <ToolbarSpacer />
      <Button size="sm" variant="outline">
        Save draft
      </Button>
      <Button size="sm" leadingIcon={<Icon name="send" />}>
        Deploy
      </Button>
    </Toolbar>
  );
}
```

### Vertical

```tsx
import { Icon, IconButton, Toolbar, ToolbarSeparator } from '@bindshq/stance-react';

export function Vertical() {
  return (
    <Toolbar aria-label="Canvas tools" orientation="vertical">
      <IconButton size="sm" variant="ghost" label="Select" icon={<Icon name="square" />} />
      <IconButton size="sm" variant="ghost" label="Text" icon={<Icon name="type" />} />
      <IconButton size="sm" variant="ghost" label="Image" icon={<Icon name="image" />} />
      <ToolbarSeparator orientation="horizontal" />
      <IconButton size="sm" variant="ghost" label="Delete" icon={<Icon name="trash" />} />
    </Toolbar>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Toolbar | `aria-label` (required) | `string` | None | Names the toolbar, e.g. “Text formatting”. |
| Toolbar | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout and arrow-key axis. |
| Toolbar | `loop` | `boolean` | `true` | Wrap focus from last to first. |
| Toolbar | `size` | `'sm' \| 'md'` | `'md'` | Spacing density. |
| Toolbar | `bordered` | `boolean` | `true` | Draw a surface and border. |
| ToolbarGroup | `aria-label` | `string` | None | Labels a cluster of related controls. |
| ToolbarSeparator | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Divider direction. |
| ToolbarSpacer | `None` | `None` | None | Pushes following controls to the far end. |

## Accessibility

- Implements the WAI-ARIA toolbar pattern: role="toolbar", aria-orientation and a roving tabindex.
- Disabled controls are skipped by arrow keys.
- Text fields inside the toolbar keep Left, Right, Home and End for editing.
- Use ToggleButton for on/off formatting so aria-pressed communicates state.
- Icon-only controls need labels; IconButton requires one.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into the toolbar (last focused control), then out of it. |
| `←` `→` | Horizontal: previous or next control (wraps). |
| `↑` `↓` | Vertical: previous or next control (wraps). |
| `Home` `End` | First or last control. |

## Guidelines

**Do**

- Group related controls and separate groups with ToolbarSeparator.
- Keep the most used actions first.

**Don’t**

- Put unrelated page navigation in a toolbar.
- Overload a toolbar; move rare actions to a menu.

## Related

- https://stanceui.com/components/toggle-button
- https://stanceui.com/components/icon-button
- https://stanceui.com/components/button-group