docs / patterns / toolbar

Toolbar

a horizontal bar over a working surface: groups of related controls on the left, a trailing actions cluster on the right, and it wraps instead of clipping.

intensity · structuresrsc · server

provenance

shaped from sisu-plus

layer

core / patterns

intensity

structures · organizes a region, stays out of the content

composition

tops a table, board, or panel it acts onsmall controls only: sm buttons, badges, legend keys, count chipsnot navigation and not a page headerno solid buttons except the one primary action in ToolbarActions

a11y

role="toolbar" on the row, give it an aria-label · swatches and count dots are aria-hiddenjest-axe
live demo · try it out
customize
maxcaps visible keys, rest collapse to +N
5
countat zero the chip renders nothing
3
tonesemantic tone for the count chip
labelthe noun after the number
usagecopy
import { Toolbar, ToolbarActions, ToolbarCount, ToolbarLegend, ToolbarLegendItem } from "@usva-ui/react/patterns/toolbar";
import { Button } from "@usva-ui/react/primitives/button";

<Toolbar aria-label="timeline toolbar">
  <ToolbarLegend>
    <ToolbarLegendItem swatch="#8b5cf6">Computer Science</ToolbarLegendItem>
    <ToolbarLegendItem swatch="#52c989">Mathematics</ToolbarLegendItem>
    <ToolbarLegendItem swatch="#e0b341">Physics</ToolbarLegendItem>
    <ToolbarLegendItem swatch="#6ea8fe">Linguistics</ToolbarLegendItem>
    <ToolbarLegendItem swatch="#e0556b">Philosophy</ToolbarLegendItem>
  </ToolbarLegend>
  <ToolbarActions>
    <ToolbarCount count={3}>unsaved</ToolbarCount>
    <Button size="sm">Confirm</Button>
  </ToolbarActions>
</Toolbar>

props

proptypedefaultnotes
rolestring"toolbar"override only when the bar is purely presentational.
ToolbarLegend · maxnumber—caps the visible keys; the rest collapse into a "+N" indicator.
ToolbarLegendItem · swatchstring—any CSS color, following StripeCard's stripeColor. unset falls back to a neutral token.
ToolbarCount · countnumber—at zero the chip renders nothing, so callers stop guarding.
ToolbarCount · tone"accent" | "accent-alt" | "success" | "warning" | "danger""accent"semantic tone for the chip and its dot.

get it

bun add @usva-ui/reactcopy
usagecopy
import { Toolbar, ToolbarActions, ToolbarGroup } from "@usva-ui/react/patterns/toolbar";
import { Button } from "@usva-ui/react/primitives/button";

<Toolbar aria-label="projects toolbar">
  <ToolbarGroup>
    <Button size="sm" variant="ghost">Filter</Button>
  </ToolbarGroup>
  <ToolbarActions>
    <Button size="sm">New</Button>
  </ToolbarActions>
</Toolbar>