Skip to content
WunderUI

Toolbar

Free

Group the buttons and links that act on one thing, so the arrow keys move between them and Tab passes the whole row.

npx wunderui-cli add toolbar

Playground

Installation

bash
npx wunderui-cli add toolbar

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Button Group for joined buttons that belong together, such as a view switch or a split action
  • Action Bar for the actions that appear for a selection of rows, with a count and a way to clear it
  • Icon Button for a single icon action that stands on its own, not in a row of actions

Groups

Related buttons sit in a ToolbarGroup, and a ToolbarSeparator splits the groups. When the row gets too long, the tools used least move behind one overflow button that opens a panel.

Selection

Toggles in a toolbar switch on and off by themselves. For a choice between alignments, keep one value in state so choosing one switches the others off.

States

A pressed toggle takes the indigo tint. A disabled button stays reachable with the arrow keys, so people know it exists, but cannot be pressed; disable the whole toolbar with one prop on the root.

Keyboard interactions

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.

TaborShiftTab
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.
ArrowLeftorArrowRight
Moves focus to the previous or next item in a horizontal toolbar. From the last item it wraps to the first, unless is .
ArrowUporArrowDown
Does the same in a vertical toolbar (). The keys of the other axis do nothing.
EnterorSpace
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 and motion

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

A framed row, its groups and the items inside. The figure shows two groups, a separator and a link, and the numbers name the parts in the list below.

  • data-slot="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.

  • data-slot="toolbar-group"Optional

    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.

  • data-slot="toolbar-button"

    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.

  • data-slot="toolbar-separator"Optional

    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.

  • data-slot="toolbar-link"Optional

    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

  • Do

    Name the toolbar with an aria-label, such as Text formatting, and give every icon-only button its own aria-label.

  • Do

    Sort buttons into groups with a separator between them, so related actions sit together and arrow keys still pass through the whole row.

  • Do

    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.

  • Do

    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

    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

    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

One table per part. Every part also takes the props of the Base UI toolbar part it wraps and of the element it renders, such as id, aria-label and onClick.

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.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"The direction of the arrow keys and of : uses left and right, uses up and down. It does not change the layout; add for a column.
loopFocusbooleantrueWhether focus wraps from the last item to the first, and back, with the arrow keys. Set to stop at the ends.
disabledboolean—Disables every item in the toolbar. The items stay reachable with the arrow keys unless a ToolbarButton sets to .
renderReactElement | (props, state) => ReactElement—Replaces the with another element or component, for example . The role and the orientation attributes are still set on it.
classNamestring | (state) => string | undefined—Extra classes for the frame, merged after its own, for example or . A function receives the state and returns the classes.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the frame. A function receives the state and returns the styles.

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.

PropTypeDefaultDescription
disabledbooleanfalseDisables every item in the group, while the rest of the toolbar stays active.
renderReactElement | (props, state) => ReactElement—Replaces the of the group with another element or component.
classNamestring | (state) => string | undefined—Extra classes for the group, such as in a vertical toolbar.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the group. A function receives the state and returns the styles.

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.

PropTypeDefaultDescription
disabledbooleanfalseDisables the button: it is drawn at 40 % opacity and ignores presses. It stays focusable with the arrow keys while is on.
focusableWhenDisabledbooleantrueKeeps a disabled button in the arrow-key order, so people can find it and read its name. Set to skip it.
nativeButtonbooleantrueSet when gives a non-button element such as a link, so the toolbar adds the button role and keyboard handling itself.
renderReactElement | (props, state) => ReactElement—Replaces the with another element or component. Pass a to make a toggle button; the button keeps its place in the roving focus.
classNamestring | (state) => string | undefined—Extra classes for the button, merged after its own, for example a wider button for a text label.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the button. A function receives the state and returns the styles.

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.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"The direction of the line. It follows the toolbar and runs across it, so leave it out.
renderReactElement | (props, state) => ReactElement—Replaces the with another element or component.
classNamestring | (state) => string | undefined—Extra classes for the line. In a vertical toolbar use to turn it into a horizontal line.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the line. A function receives the state and returns the styles.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("toolbar")
Installnpx wunderui-cli add toolbar

The full library index for assistants is at /llms.txt.