# Toolbar

A container for grouping a set of buttons and controls.

- Category: Core Elements
- Page: https://wunderui.com/components/toolbar
- Tier: Free

## Install

```bash
npx wunderui-cli add toolbar
```

## Import

```tsx
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarLink, ToolbarSeparator } from "@/components/ui/toolbar"
```

## Minimal usage

Then use it:

```tsx
import { Bold, Italic } from "lucide-react"
import { Toolbar, ToolbarButton, ToolbarGroup } from "@/components/ui/toolbar"

export function Formatting() {
  return (
    <Toolbar aria-label="Text formatting">
      <ToolbarGroup>
        <ToolbarButton aria-label="Bold">
          <Bold />
        </ToolbarButton>
        <ToolbarButton aria-label="Italic">
          <Italic />
        </ToolbarButton>
      </ToolbarGroup>
    </Toolbar>
  )
}
```

Expected result: A framed row with two 32 px icon buttons, bold and italic. Tab puts focus on the first one, and arrow keys move between them.

## Usage

```tsx
import { AlignCenter, AlignLeft, AlignRight, Bold, Italic, Underline } from "lucide-react"
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator } from "@/components/ui/toolbar"

export function Example() {
  return (
    <Toolbar aria-label="Text formatting">
      <ToolbarGroup>
        <ToolbarButton aria-label="Bold"><Bold /></ToolbarButton>
        <ToolbarButton aria-label="Italic"><Italic /></ToolbarButton>
        <ToolbarButton aria-label="Underline"><Underline /></ToolbarButton>
      </ToolbarGroup>
      <ToolbarSeparator />
      <ToolbarGroup>
        <ToolbarButton aria-label="Align left"><AlignLeft /></ToolbarButton>
        <ToolbarButton aria-label="Align center"><AlignCenter /></ToolbarButton>
        <ToolbarButton aria-label="Align right"><AlignRight /></ToolbarButton>
      </ToolbarGroup>
    </Toolbar>
  )
}
```

## When to use

### Use Toolbar for

- The formatting buttons above an editor, the tools of a canvas or the actions of a selection
- A row of icon buttons that should be one tab stop with arrow-key movement
- Toggles that switch a style on or off, alone or as one of a set

### Use something else

- [Button Group](https://wunderui.com/components/button-group) for joined buttons that belong together, such as a view switch or a split action
- [Action Bar](https://wunderui.com/components/action-bar) for the actions that appear for a selection of rows, with a count and a way to clear it
- [Icon Button](https://wunderui.com/components/icon-button) for a single icon action that stands on its own, not in a row of actions

## Keyboard

The toolbar is built on the Base UI toolbar. It keeps one item in the tab order and moves focus between the items with arrow keys.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the toolbar, onto the item that last had focus (the first one at the start), and out of it again. The toolbar is one tab stop however many items it holds. |
| `ArrowLeft` or `ArrowRight` | Moves focus to the previous or next item in a horizontal toolbar. From the last item it wraps to the first, unless `loopFocus` is `false`. |
| `ArrowUp` or `ArrowDown` | Does the same in a vertical toolbar (`orientation="vertical"`). The keys of the other axis do nothing. |
| `Enter` or `Space` | Presses the focused button. On a toggle it switches it on or off. On a ToolbarLink, Enter follows the link. |

Disabled buttons stay reachable with arrow keys because they remain focusable by default. Turn that off on a button to skip it.

## Behavior

What the toolbar does with focus, state, layout and motion.

- **Role and name:** The root has the toolbar role and an orientation. Give it an aria-label so a screen reader announces what it is, and a group has the group role.
- **Focus:** Focus is roving: one item is in the tab order and arrow keys move it. The focused item draws a 2 px indigo ring on its edge, which fits in the 4 px padding and is not clipped.
- **Pressed:** A ToolbarButton is a plain button, and rendering it as a Toggle makes it report pressed. The pressed button takes the indigo tint, border and text, and keeps the tint on hover.
- **Disabled:** A disabled item or toolbar is announced as disabled, drawn at 40 % opacity and ignores the pointer. It stays in the arrow-key order unless you turn that off.
- **Orientation:** Vertical orientation only changes the arrow keys and the announced orientation. The layout stays a row until you stack the toolbar and groups, and the separator then needs a horizontal line style.
- **Concentric corners:** The 8 px button corner sits 4 px inside the 12 px toolbar corner. A toolbar with larger buttons and more padding needs a larger corner, for example 16 px for 8 px of padding.
- **Theme:** The frame uses the card and border tokens, and buttons use secondary text with page and subtle fills for hover and pressed. They follow the theme and dark mode with no extra class.
- **Motion:** A button fades its colour on hover and press. Only colour animates, and nothing moves or resizes.
- **Reduced motion:** Nothing moves, so there is no animation to remove. The colour change is the same with reduced motion.

## Anatomy

- `Toolbar`: A framed row with the toolbar role, a 1 px border, the card fill and a 12 px corner, with 4 px of padding and gaps. It is one tab stop with arrow keys between items, named with an aria-label.
- `ToolbarGroup`: Keeps related buttons close together with a 2 px gap, such as the text styles. It has the group role, and disabling it disables every item inside.
- `ToolbarButton`: A 32 px square button with an 8 px corner for one icon. It joins the roving focus, and becomes a toggle when you render it as one: a pressed one takes the indigo tint.
- `ToolbarSeparator`: A 1 px line between two groups, 20 px long with 4 px of margin on each side. It runs across the toolbar, vertical in a horizontal one and horizontal in a vertical one.
- `ToolbarLink`: A 14 px text link in the toolbar that arrow keys reach like the buttons. Use it for a destination such as a help page, and a button for an action.

## Best practices

### When to use

- Use it for controls that act on one thing, such as the formatting buttons of an editor or the tools of a canvas. For joined buttons that switch a view, use a Button Group.

### Do

- Name the toolbar with an aria-label, such as Text formatting, and give every icon-only button its own aria-label.
- Sort buttons into groups with a separator between them, so related actions sit together and arrow keys still pass through the whole row.
- Show a tooltip with the name and shortcut on every icon button, and wrap one toolbar's tooltips in one TooltipProvider so they share a delay.
- Keep a toolbar to one row of 4 to 12 items. When you need more tools, move the least used behind an overflow button instead of letting the row scroll.

### Don't

- Don't add your own arrow-key handling or tabIndex to the items. The toolbar already moves focus between them, and Tab leaves it.
- Don't swap a button for a menu, select or field without testing it with the keyboard. Only buttons, links and inputs of the toolbar take part in its roving focus.
- Don't use a Toolbar to navigate between pages. Use tabs or a navigation bar, since a toolbar is for actions on the thing in front of the user.

## API reference

### Toolbar

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the frame, merged after its own, for example `w-fit` or `flex-col`. A function receives the state and returns the classes. |
| disabled | boolean |  | Disables every item in the toolbar. The items stay reachable with the arrow keys unless a ToolbarButton sets `focusableWhenDisabled` to `false`. |
| loopFocus | boolean | true | Whether focus wraps from the last item to the first, and back, with the arrow keys. Set `false` to stop at the ends. |
| orientation | "horizontal" \| "vertical" | 'horizontal' | The direction of the arrow keys and of `aria-orientation`: `horizontal` uses left and right, `vertical` uses up and down. It does not change the layout; add `flex-col` for a column. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the `<div>` with another element or component, for example `render={<nav />}`. The role and the orientation attributes are still set on it. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the frame. A function receives the state and returns the styles. |

Also accepts React.HTMLAttributes attributes.

### ToolbarButton

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the button, merged after its own, for example a wider button for a text label. |
| disabled | boolean | false | Disables the button: it is drawn at 40 % opacity and ignores presses. It stays focusable with the arrow keys while `focusableWhenDisabled` is on. |
| focusableWhenDisabled | boolean | true | Keeps a disabled button in the arrow-key order, so people can find it and read its name. Set `false` to skip it. |
| nativeButton | boolean | true | Set `false` when `render` gives a non-button element such as a link, so the toolbar adds the button role and keyboard handling itself. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the `<button>` with another element or component. Pass a `Toggle` to make a toggle button; the button keeps its place in the roving focus. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the button. A function receives the state and returns the styles. |

Also accepts React.ButtonHTMLAttributes attributes.

### ToolbarGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the group, such as `flex-col` in a vertical toolbar. |
| disabled | boolean | false | Disables every item in the group, while the rest of the toolbar stays active. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the `<div>` of the group with another element or component. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the group. A function receives the state and returns the styles. |

Also accepts React.HTMLAttributes attributes.

### ToolbarLink

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the link, merged after its own, for example `px-1` to give it some air. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the `<a>` with another element or component, such as the link of your router. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the link. A function receives the state and returns the styles. |

Also accepts React.AnchorHTMLAttributes attributes.

### ToolbarSeparator

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the line. In a vertical toolbar use `mx-0 my-1 h-px w-5` to turn it into a horizontal line. |
| orientation | "horizontal" \| "vertical" | 'horizontal' | The direction of the line. It follows the toolbar and runs across it, so leave it out. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the `<div>` with another element or component. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the line. A function receives the state and returns the styles. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Groups: one group, groups split by separators and an overflow button

```tsx
import { AlignCenter, AlignLeft, AlignRight, Bold, Italic } from "lucide-react"
import { Toolbar, ToolbarButton, ToolbarGroup } from "@/components/ui/toolbar"

export function Example() {
  return (
    <Toolbar aria-label="Text formatting">
      <ToolbarGroup>
        <ToolbarButton aria-label="Bold"><Bold /></ToolbarButton>
        <ToolbarButton aria-label="Italic"><Italic /></ToolbarButton>
        <ToolbarButton aria-label="Align left"><AlignLeft /></ToolbarButton>
        <ToolbarButton aria-label="Align center"><AlignCenter /></ToolbarButton>
        <ToolbarButton aria-label="Align right"><AlignRight /></ToolbarButton>
      </ToolbarGroup>
    </Toolbar>
  )
}
```

### Selection: toggles on their own and one of a set

```tsx
import { Bold, Italic, Underline } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"
import { Toolbar, ToolbarButton, ToolbarGroup } from "@/components/ui/toolbar"

export function Example() {
  return (
    <Toolbar aria-label="Text style">
      <ToolbarGroup>
        <ToolbarButton render={<Toggle aria-label="Bold" defaultPressed />}><Bold /></ToolbarButton>
        <ToolbarButton render={<Toggle aria-label="Italic" />}><Italic /></ToolbarButton>
        <ToolbarButton render={<Toggle aria-label="Underline" />}><Underline /></ToolbarButton>
      </ToolbarGroup>
    </Toolbar>
  )
}
```

### States: default, pressed, one item disabled and the whole toolbar disabled

```tsx
import { Bold, Italic, Underline } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"
import { Toolbar, ToolbarButton, ToolbarGroup } from "@/components/ui/toolbar"

export function Example() {
  return (
    <Toolbar aria-label="Text style">
      <ToolbarGroup>
        <ToolbarButton render={<Toggle aria-label="Bold" />}><Bold /></ToolbarButton>
        <ToolbarButton render={<Toggle aria-label="Italic" />}><Italic /></ToolbarButton>
        <ToolbarButton render={<Toggle aria-label="Underline" />}><Underline /></ToolbarButton>
      </ToolbarGroup>
    </Toolbar>
  )
}
```

## In context

### Text editor: formatting toggles with tooltips

The three toggles share one TooltipProvider, so the first tooltip opens after the delay and the next ones open at once. The line of text follows the toggles.

```tsx
import { useState, type ReactNode } from "react"
import { Bold, Italic, Underline } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"
import { Toolbar, ToolbarButton, ToolbarGroup } from "@/components/ui/toolbar"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

function Tool({
  label,
  shortcut,
  pressed,
  onPressedChange,
  children,
}: {
  label: string
  shortcut: string
  pressed: boolean
  onPressedChange: (pressed: boolean) => void
  children: ReactNode
}) {
  return (
    <Tooltip>
      <TooltipTrigger
        describe={false}
        render={<ToolbarButton render={<Toggle aria-label={label} pressed={pressed} onPressedChange={onPressedChange} />} />}
      >
        {children}
      </TooltipTrigger>
      <TooltipContent shortcut={shortcut}>{label}</TooltipContent>
    </Tooltip>
  )
}

export function Example() {
  const [bold, setBold] = useState(false)
  const [italic, setItalic] = useState(false)
  const [underline, setUnderline] = useState(false)
  return (
    <TooltipProvider>
      <div className="flex w-96 max-w-full flex-col gap-3">
        <Toolbar aria-label="Text formatting" className="w-fit">
          <ToolbarGroup>
            <Tool label="Bold" shortcut="⌘B" pressed={bold} onPressedChange={setBold}>
              <Bold />
            </Tool>
            <Tool label="Italic" shortcut="⌘I" pressed={italic} onPressedChange={setItalic}>
              <Italic />
            </Tool>
            <Tool label="Underline" shortcut="⌘U" pressed={underline} onPressedChange={setUnderline}>
              <Underline />
            </Tool>
          </ToolbarGroup>
        </Toolbar>
        <p
          className={[
            "rounded-xl border border-border bg-card p-4 text-sm text-foreground",
            bold ? "font-semibold" : "",
            italic ? "italic" : "",
            underline ? "underline" : "",
          ].join(" ")}
        >
          The quarterly report is ready for review. Revenue grew 12 percent to $1,842,000.
        </p>
      </div>
    </TooltipProvider>
  )
}
```

### Canvas tools: a vertical toolbar where one tool is on at a time

A vertical toolbar uses the up and down arrow keys. The library sizes the separator for a row, so turn it into a horizontal line with a class.

```tsx
import { useState } from "react"
import { Hand, MousePointer2, Square, Type } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator } from "@/components/ui/toolbar"

export function Example() {
  const [tool, setTool] = useState("Select")
  return (
    <div className="flex items-stretch gap-4">
      <Toolbar aria-label="Tools" orientation="vertical" className="w-fit flex-col">
        <ToolbarGroup className="flex-col">
          <ToolbarButton
            render={<Toggle aria-label="Select" pressed={tool === "Select"} onPressedChange={() => setTool("Select")} />}
          >
            <MousePointer2 />
          </ToolbarButton>
          <ToolbarButton
            render={<Toggle aria-label="Rectangle" pressed={tool === "Rectangle"} onPressedChange={() => setTool("Rectangle")} />}
          >
            <Square />
          </ToolbarButton>
          <ToolbarButton
            render={<Toggle aria-label="Text" pressed={tool === "Text"} onPressedChange={() => setTool("Text")} />}
          >
            <Type />
          </ToolbarButton>
        </ToolbarGroup>
        <ToolbarSeparator className="mx-0 my-1 h-px w-5" />
        <ToolbarButton
          render={<Toggle aria-label="Hand" pressed={tool === "Hand"} onPressedChange={() => setTool("Hand")} />}
        >
          <Hand />
        </ToolbarButton>
      </Toolbar>
      <div className="flex w-40 items-center justify-center rounded-xl border border-border bg-card text-sm text-text-secondary">
        Tool: {tool}
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("toolbar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
