Toolbar

When to use

• A dense, persistent bar of controls that act on one thing: a text selection, a canvas, a table, the rows picked in a list. It is one tab stop with the arrow keys inside, so a keyboard user passes the whole bar in one press.
• Frequent actions for the current view or task. Put the commands people reach for most first, and group related ones with ToolbarGroup and separators.
• Mixed controls in one bar: buttons, toggles (pressed), links and one input, with ToolbarSpacer pushing trailing items to the far edge.
• Destructive actions kept apart. Mark the item intent="error" and set it off from its neighbours with a separator or a spacer.
• One line. A toolbar never wraps: a bar with more tools than width scrolls along its own axis, or moves the tools people rarely need into an overflow menu.

When not to use

• For a few related actions that should each be their own tab stop. Use a Button Group; a group deliberately has no roving focus.
• For an application's top-level menus (File, Edit, View), where every item opens a menu. Use a Menubar.
• To pick one of a few options that changes a value or a view setting. Use a Segmented Control. Inside a toolbar, a cluster with real selection state is a Toggle Group composed into the bar.
• To switch between views. Selecting a view changes context rather than acting on the current one. Use Tabs.
• For a bar that rides above the software keyboard on a phone. Use a Keyboard Toolbar; it wraps a normal toolbar.
• To hold every action a page has. A bar crowded past the point where each item can be told apart and hit helps nobody; keep the common tools visible and move the rest behind a menu.

Installation

pnpm add @tessinaui/ui

Usage

import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarLink,
  ToolbarInput,
  ToolbarSeparator,
  ToolbarSpacer,
} from "@tessinaui/ui";

{/* Formatting bar — `pressed` derives `aria-pressed`, so state is announced. */}
function FormatToolbar() {
  const [bold, setBold]     = useState(true);
  const [italic, setItalic] = useState(false);
  const [align, setAlign]   = useState("left");

  return (
    <Toolbar aria-label="Format text">
      <ToolbarButton iconOnly leadingIcon={<Undo2 />} aria-label="Undo" />
      <ToolbarSeparator />
      <ToolbarButton iconOnly leadingIcon={<Bold />} aria-label="Bold"
        pressed={bold} onClick={() => setBold((v) => !v)} />
      <ToolbarButton iconOnly leadingIcon={<Italic />} aria-label="Italic"
        pressed={italic} onClick={() => setItalic((v) => !v)} />
      <ToolbarSeparator />
      <ToolbarButton iconOnly leadingIcon={<AlignLeft />} aria-label="Align left"
        pressed={align === "left"} onClick={() => setAlign("left")} />
      <ToolbarButton iconOnly leadingIcon={<AlignCenter />} aria-label="Align center"
        pressed={align === "center"} onClick={() => setAlign("center")} />
      <ToolbarSpacer />
      <ToolbarLink href="/help">Help</ToolbarLink>
    </Toolbar>
  );
}

{/* Table action bar — the input goes LAST, and the bar scrolls when narrow. */}
<Toolbar variant="outline" overflow="scroll" aria-label="Table actions">
  <ToolbarButton leadingIcon={<Filter />} trailingIcon={<ChevronDown />}>Filter</ToolbarButton>
  <ToolbarButton leadingIcon={<Plus />}>Add row</ToolbarButton>
  <ToolbarSpacer />
  <ToolbarInput placeholder="Search…" aria-label="Search rows" />
</Toolbar>

{/* Floating canvas bar */}
<Toolbar variant="floating" rounded="full" aria-label="Selection tools">
  <ToolbarButton iconOnly leadingIcon={<Bold />} aria-label="Bold" pressed />
  <ToolbarButton iconOnly leadingIcon={<Italic />} aria-label="Italic" />
</Toolbar>

Examples

Default

Icon buttons in labelled groups, divided by separators.

Variants

Five surfaces — soft (default, a recessed well), solid, outline, ghost, and floating for a bar detached from what it sits over.

Sizes

sm, md and lg drive the item heights — 32 / 36 / 40px, putting the bar at 40 / 44 / 48.

Rounded

Every corner derives from one rounded value: the bar, each item and a contained group step together, so the items always tuck inside the bar's silhouette.

Groups

ToolbarGroup clusters related items and names them for assistive technology. variant="contained" gives the cluster its own tinted well. On a colour plate over a soft or floating bar, which already is that well, it outlines itself instead of stacking a second wash.

Pressed

pressed paints the raised plate and derives aria-pressed. The bar does not own the state — these are independent toggles held by the consumer.

Real toggle state

When a cluster needs controlled state, single- or multi-selection and a change event, compose a ToggleGroup inside the bar rather than wiring pressed by hand.

Overflow — scroll

A toolbar never wraps to a second line, so a bar with more tools than width becomes a rail along its own axis. This is the default, because it costs nothing while the items fit and it is what every phone editor ships.

Overflow — paging chevron

A rail only announces itself once you touch it. overflowAffordance pins a chevron at the end that pages the bar, so the hidden items are visible as a target rather than as a guess.

It renders only while the content actually overflows (measured with a ResizeObserver and a MutationObserver, so an item added later still counts), and it turns round at the end rather than going dead. Switching it on moves the items into an inner toolbar-rail element so the button can sit beside the rail instead of scrolling away with it — which is why it is opt-in: a bar that fits should not pay for the extra element.

Needs overflow="scroll" (the default). Under overflow="none" the bar clips, so there is nothing to page to, and the prop warns in development instead of rendering a button that cannot work.

Overflow — menu

The alternative: keep the frequent tools visible and put the rest behind a trailing menu. Unlike a rail, nothing ends up off-screen.

Menus

A menu opened from the bar. The trigger is a ToolbarButton passed through the menu's render, so it keeps its place in the roving focus instead of becoming a second tab stop.

Floating

A bar with a surface of its own, lifted off the content. Pinned to the bottom of a phone screen with the safe-area inset, this is the keyboard accessory bar.

Search and actions

Leading tools, trailing actions, and the real Search component filling the rest of the bar, so the field never ends up squeezed into the corner. Reach for ToolbarSpacer instead when the trailing item should keep its natural size.

Search reaches the bar through ToolbarInput's render: its input joins the bar's roving focus — arrows still traverse, Tab still leaves — while Search keeps the magnifier, Escape-to-clear, the clear button, the iOS search keyboard and its polite result-count region. Pass noForm (Search is a <form> by default, and nested forms are invalid HTML), size it from inputFieldSizeFor[size] so it matches item height at every bar density, and give it a layout box through wrapperClassName — Search's root is w-full and would otherwise claim the whole row.

Selection bar

A count, the actions that apply to it, and a way out — the batch-action bar over a list or a grid. The destructive action takes intent="error".

Labeled items

The stacked icon-over-label item media editors ship. A className recipe rather than a prop; a stacked item clears the 44px touch floor on its own.

In flight

loading announces aria-busy, swallows activation and shows the spinner — while the item stays focusable, so a request in progress never throws the user's focus back to the start of the bar.

Vertical

orientation="vertical" stacks the items into a rail. At rounded="full" the bar derives a stadium radius from its own item height rather than clipping into an oval.

RTL

dir="rtl" mirrors the layout and flips the arrow keys. Unset, the bar does the same on an RTL page.

Disabled

A disabled item stays reachable by arrow key, so a user can discover that a tool exists and is currently unavailable. disabled on the bar cascades to every item.

On color

Inside a coloured Surface the bar inherits on-color: a soft or floating bar paints the plate's well, and a pressed item becomes the plate's inverse chip. Pass tone to override the inherited value.

Skeleton

The placeholder paints from the same cvas the real bar renders with, so its geometry cannot drift from the component.

Composition

The toolbar is a focus-traversal container: arrow keys move between items, Tab leaves for the next region. Any focusable primitive composes inside it.

Give the bar a name. A screen reader announces the role and then has nothing to say about which bar this is. In development, an unnamed Toolbar — or an unnamed iconOnly item — logs a warning.

Toggle state. pressed on a ToolbarButton is a per-item visual flag that derives aria-pressed for you:

const [bold, setBold] = useState(false);

<ToolbarButton
  iconOnly
  leadingIcon={<Bold />}
  aria-label="Bold"
  pressed={bold}
  onClick={() => setBold((v) => !v)}
/>

For a cluster that needs real state — controlled or uncontrolled, single- or multi-select, with a change event — compose ToggleGroup inside the bar instead. Pair the sizes deliberately: the toolbar's sm / md / lg items are 32 / 36 / 40px, which line up with ToggleGroup's xs / xs / sm.

Menus, selects and tooltips compose through Base UI's render, which keeps the trigger inside the roving focus:

{/* A menu opened from the bar */}
<DropdownMenuTrigger
  render={<ToolbarButton iconOnly leadingIcon={<MoreHorizontal />} aria-label="More tools" />}
/>

{/* A tooltip — note the direction reverses: the item goes INTO the trigger */}
<Tooltip>
  <TooltipTrigger render={<ToolbarButton iconOnly leadingIcon={<Bold />} aria-label="Bold" />} />
  <TooltipContent>Bold ⌘B</TooltipContent>
</Tooltip>

An icon-only item needs both a tooltip (for sighted users) and an aria-label (for everyone else). The tooltip is not an accessible name.

API Reference

Toolbar (root)

ToolbarButton

ToolbarLink

The same shape as ToolbarButton, rendering an <a>. Pass href and the usual anchor attributes.

ToolbarInput

Place at most one, last. Left/right arrows move the caret as well as traversing the bar, so items after an input are reachable only once the caret has run to the end of the value. A second input in one bar warns in development.

A composite may mount controls of its own inside the field — Search's clear button appears once the value is non-empty — and those are ordinary tab stops. An untouched bar is still one tab stop; a dirty one is two.

ToolbarGroup

ToolbarSeparator

Orientation-aware rule: a vertical line in a horizontal bar, a horizontal one in a vertical bar. Inset off both ends and deliberately fainter than --border, which reads as a wall between buttons.

ToolbarSpacer

A spring that pushes everything after it to the trailing edge. It is Spacer with grow, on the bar's own axis, and keeps its own data-slot="toolbar-spacer". Under overflow="scroll" it collapses to zero before the rail starts scrolling — fill the bar, then scroll.

ToolbarSkeleton

Plus size, variant, rounded, orientation and tone, which mirror the real bar.

Notes

• A toolbar never wraps. A second row destroys the single-line scan the bar exists for, and the alternative broke ToolbarSpacer: once a row wrapped, the spacer took a line of its own and stopped pushing. What it does instead is overflow's business — scroll (the default) rails, none clips. Neither lets content escape, because an unclipped bar pushes the whole page sideways, which is WCAG 1.4.10: measured at up to 98px on six of the examples below before the clip existed. To keep every action visible at any width, move the surplus into an overflow menu.
• Pressed items render as a raised plate lifted off the well — the same treatment SegmentedControl gives its thumb, so the two read as one family. On a page-coloured bar (outline, floating, ghost) nothing can lift above the background, so the pressed state recesses into the well instead. It stays visible in Windows high-contrast. On a coloured plate both are the inverse chip — the plate's own ink, labelled with the neutral that contrasts it — because a wash of the ink cannot hold a label at 4.5:1 on the error, info and success plates.
• RTL — on an RTL page the bar mirrors its layout and its arrow keys with no prop. dir sets a direction the page around it does not have.
• Touch — every item clears 44×44px wherever touch is the pointer, phones and tablets alike (the input included, which its own flex-1 would otherwise squeeze to 26px), while a mouse or trackpad keeps the compact density, and ToolbarInput renders at 16px on touch so iOS Safari does not zoom the page on focus.

Accessibility

Pattern: WAI-ARIA Toolbar.

• One tab stop, arrow keys inside. Built on @base-ui/react/toolbar, the bar renders role="toolbar" with aria-orientation and a roving tabindex: Tab enters on one item and leaves for the next region, arrows move between items. A rail under overflow="scroll" scrolls the focused item into view.
• Name the bar. Pass aria-label (or aria-labelledby); an unnamed Toolbar, or an unnamed iconOnly item, warns in development. Name a ToolbarGroup whose purpose is not self-evident. An icon-only item needs both a tooltip and an aria-label — the tooltip is not an accessible name.
• Toggle state is announced. pressed derives aria-pressed before your props spread, so a stray prop cannot desynchronise the announced state from the painted one. loading sets aria-busy, swallows activation and keeps the item focusable.
• Disabled items stay focusable by default, matching Base UI and WAI-ARIA: a user arrowing along the bar should be able to discover that a tool exists and is unavailable, rather than have it silently vanish.
• The paging chevron is part of the bar. overflowAffordance renders a named button inside the item list, and its name flips between "Scroll forward" and "Scroll back" as the rail reaches an end (overflowAffordanceLabels localises both).
• Separators are orientation-aware and convey the grouping to assistive tech.
• ToolbarInput shares the arrow keys with the caret — place at most one, last (see ToolbarInput).
• Contrast — pressed state stays visible in Windows high contrast; on a coloured plate the pressed chip is the plate's own ink with a contrasting label, because a wash cannot hold 4.5:1 on the error, info and success plates. axe color-contrast is clean on the demo and playground in both themes.
• Touch — every item clears 44×44px on touch devices, phones and tablets alike.

Keyboard

AT matrix

VoiceOver steps past a toolbar as one unit: Control+Option+Shift+↓ interacts into it. One NVDA pass is still owed.