Toolbar

Grouped controls for rich editors and tool palettes with roving focus, toggle groups, links, and separators.

Installation

The components are exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Build a Toolbar from ToolbarToggleGroup / ToolbarToggleItem, ToolbarButton, ToolbarLink, and ToolbarSeparator:

Toolbar
├── ToolbarToggleGroup
│   └── ToolbarToggleItem …
├── ToolbarSeparator (optional)
├── ToolbarButton | ToolbarLink …
└── …

Other primitives with asChild triggers (for example DropdownMenu) can be composed inside the toolbar per Radix composition. See Radix Toolbar.

Usage

import {
  Toolbar,
  ToolbarButton,
  ToolbarSeparator,
  ToolbarToggleGroup,
  ToolbarToggleItem,
} from '@by/experience-system';

All toolbar parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<Toolbar aria-label="Actions" orientation="horizontal" loop>
  <ToolbarToggleGroup type="single" defaultValue="left" aria-label="Align">
    <ToolbarToggleItem value="left" aria-label="Left">
      L
    </ToolbarToggleItem>
    <ToolbarToggleItem value="right" aria-label="Right">
      R
    </ToolbarToggleItem>
  </ToolbarToggleGroup>
  <ToolbarSeparator />
  <ToolbarButton type="button">Save</ToolbarButton>
</Toolbar>

Examples

Overview

Multiple and single ToolbarToggleGroup regions, a ToolbarLink, and a ToolbarButton (same preview as at the top of the page).

Toggle groups

Two groups only—style (multiple) and alignment (single).

Link

ToolbarButton with ToolbarLink items for secondary navigation.

The tables below mirror the Radix UI Toolbar API. Subsection titles match @by/experience-system exports. ToolbarButton and ToolbarLink layer Button styles on Radix Toolbar.Button and Toolbar.Link.

Prop	Type	Default
`asChild`	`boolean`	`false`
`orientation`	`horizontal` \| `vertical`	`horizontal`
`dir`	`ltr` \| `rtl`	—
`loop`	`boolean`	`true`

Data attribute	Values
`data-slot`	`toolbar`
`data-orientation`	`horizontal` \| `vertical`

ToolbarButton

Prop	Type	Default
`asChild`	`boolean`	`false`
`variant`	`Button` `variant` values	`outline`
`size`	`Button` `size` values	`sm`
`color`	`Button` `color` values	`neutral`

Data attribute	Values
`data-slot`	`toolbar-button`
`data-color`	mirrors `color`
`data-orientation`	`horizontal` \| `vertical`

ToolbarLink

Prop	Type	Default
`asChild`	`boolean`	`false`
`size`	`Button` `size` values	`sm`

Data attribute	Values
`data-slot`	`toolbar-link`
`data-orientation`	`horizontal` \| `vertical`

ToolbarSeparator

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`data-slot`	`toolbar-separator`
`data-orientation`	`horizontal` \| `vertical`

ToolbarToggleGroup

Prop	Type	Default
`asChild`	`boolean`	`false`
`type`	`single` \| `multiple`	— (required)
`value`	`string` or `string[]`	—
`defaultValue`	`string` or `string[]`	—
`onValueChange`	`(value: string \| string[]) => void`	—
`disabled`	`boolean`	`false`
`variant`	`outline` \| `ghost`	`ghost`
`size`	`sm` \| `md` \| `lg`	`sm`

Data attribute	Values
`data-slot`	`toolbar-toggle-group`
`data-orientation`	`horizontal` \| `vertical`

ToolbarToggleItem

Prop	Type	Default
`asChild`	`boolean`	`false`
`value`	`string`	— (required)
`disabled`	`boolean`	—
`variant`	`outline` \| `ghost`	From group context
`size`	`sm` \| `md` \| `lg`	From group context

Data attribute	Values
`data-slot`	`toolbar-toggle-item`
`data-state`	`on` \| `off`
`data-disabled`	Present when disabled
`data-orientation`	`horizontal` \| `vertical`

Accessibility

Label the Toolbar and each ToolbarToggleGroup with aria-label (or aria-labelledby). Icon-only ToolbarToggleItem values need aria-label. Radix uses roving tabindex across toolbar items. See Radix Toolbar — accessibility.

Keyboard interactions

Key	Description
`Tab`	Moves focus into the toolbar (first item).
`Space`	Activates or toggles the focused item.
`Enter`	Activates or toggles the focused item.
`ArrowRight` / `ArrowDown`	Moves focus to the next item (depends on `orientation`).
`ArrowLeft` / `ArrowUp`	Moves focus to the previous item.
`Home`	Moves focus to the first item.
`End`	Moves focus to the last item.

Source in the repo: packages/experience-system/src/components/Toolbar/Toolbar.tsx. Agent-oriented contracts: packages/experience-system/src/components/Toolbar/Toolbar.instructions.md.