Toolbar

Two ways of putting actions next to each other, with opposite meanings. A button group says these are alternatives. A toolbar says these apply to what you are looking at. Confusing the two is how a clinician ends up applying an action to the wrong patient.

Overview

Both components exist to make a relationship visible without words. Adjacency is the whole message, so it has to be truthful: things touching each other are read as belonging to the same decision, and things in a bar above a table are read as acting on that table.

The failure mode is the same for both — an action whose target is ambiguous. In a clinical worklist that ambiguity is not cosmetic. "Acknowledge" in a toolbar that appears to float between two panels is an acknowledgement of something, and the clinician has to guess what.

Which one

Anatomy

Button group

Segments share edges because the choice is exclusive. If two adjacent buttons can both be pressed, or if pressing one does not deselect the other, it is not a button group — it is two buttons that have been glued together by mistake.

• Never mix modes and commands. A group containing "0/1 h", "0/2 h" and "Export" has one button that does not belong; it is the one that will be pressed by accident.
• Never a split button for a clinical commit. The default half of a split button is invisible until pressed. See Menu.
• Five segments maximum. Past that, targets shrink below the 24 px minimum on narrow viewports and the group starts to reflow.
• The group never wraps. A wrapped segmented control reads as two separate controls with two separate selections.

Split buttons, and when not to

A split button pairs a default action with a menu of alternatives behind an attached control. It is a space-saving device with a specific hazard: the two halves are adjacent, differ by a few millimetres, and do different things — which is the adjacent-control error that Touch & gestures names as the dominant touch failure in gloved use.

• Both halves carry a 44 px target and are separated by a visible divider. Where the surface is gloved, the whole construct becomes two separate buttons instead.
• The default half states what it does — "Export CSV", not "Export" with the format hidden in the menu. A default action nobody can name from the label is a default action that gets pressed by accident.
• Choosing from the menu does not change the default for next time. Silent adaptation means the same press produces different results on different days, which is the one property a repeated action must not have.
• The menu half is a separate control with aria-haspopup and its own accessible name — "More export formats" — not an unlabelled chevron sharing the button's name.

Scope and selection

• Bulk acknowledgement does not exist. No toolbar in this system offers it, at any priority, for any selection size.
• The selection toolbar replaces nothing. It appears in addition to the view toolbar rather than swapping it out, so the clinician does not lose the controls they were using.
• Selection survives a sort. If it cannot, the toolbar clears it explicitly and says so, rather than silently acting on different rows.

States

A toolbar that changes shape

Mainstream systems offer several ways for a toolbar to rearrange itself: a tool picked from the overflow menu takes the place of the last tool in its group; a tool with a nested menu is replaced by whichever variant is chosen from it; tools can be dragged into a new order; the whole bar can be floated and docked wherever the reader likes. Each is offered as configurability. Together they mean the button under your finger is not the button that was there last time.

What remains permitted is deliberate and rare: the set of tools may differ by view, because a different view is a different task; and it may differ by role, because a control someone may not use is better absent than disabled. Both are decided before the clinician arrives, not by what they did a moment ago.

What the component enforces, and what it only asks for

The keyboard contract is held — it was not, until an interaction test was written for it. Everything about what is in the bar is yours.

Do's and don'ts

Accessibility

• One tab stop per toolbar or group. Tab enters and leaves; arrow keys move inside. A toolbar of twelve controls must not cost twelve tab presses on the way to the waveform.
• Roving tabindex — the last-focused control keeps focus when the toolbar is re-entered.
• role="toolbar" with an aria-label naming the scope, and aria-controls pointing at the region it acts on.
• Groups inside a toolbar use role="group" with their own label. The visual separator is aria-hidden.
• Toggle state is aria-pressed, never colour alone and never a class name.
• Targets stay ≥ 24 px with ≥ 24 px spacing between adjacent clickable centres (WCAG 2.2 SC 2.5.8). Segments that share a border still need real height — 44 px in gloved-use contexts, see Density & scaling.
• Overflow is reachable by keyboard at every viewport width, and its contents are announced as a menu, not as a dialog.
• Never aria-disabled without an explanation in the accessible name or a linked description.

Outcomes of use

What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.

• Effectiveness — the action taken lands on the thing the clinician believed they had selected.
• Efficiency — one tab stop rather than a dozen; grouping that answers "which of these is a mode?" without a click.
• Satisfaction — controls that stay where they were. A toolbar that rearranges itself between visits is a small, repeated cost to trust.

Clinical safety notes

• Scope named in the toolbar and in the action label. (you) Mitigates: an action applied to the wrong patient or the wrong recording.
• Selection count restated in the button. (you) Mitigates: a selection that changed between intention and click.
• No bulk acknowledgement anywhere. (you) Mitigates: unread alarms cleared as a batch.
• Destructive and irreversible actions never in overflow. (you) Mitigates: a high-consequence action reached by accident from a collapsed menu.
• Fixed overflow order. (you) Mitigates: motor memory landing on a different action at a different window width.
• Modes and commands never share a segmented control. (you) Mitigates: a command fired while switching views.
• Commands removed rather than disabled in read-only contexts. (you) Mitigates: a legitimate permission state read as a system fault.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/toolbar.json

<Toolbar label= "ECG review actions" >
  <ButtonGroup label= "Lead layout" >
    <Button variant= "outline"  aria-pressed={layout ===  "12x1" }>12 × 1</Button>
    <Button variant= "outline"  aria-pressed={layout ===  "6x2" }>6 × 2</Button>
  </ButtonGroup>
  <ToolbarSeparator />
  <Button variant= "outline" >Compare with prior</Button>
</Toolbar>

// One tab stop; arrow keys move between the controls and follow the
// reading direction. A ButtonGroup is related actions — if the buttons are
// mutually exclusive states, that is a RadioGroup.

What the component takes. This table used to list scope, controls, overflowFrom, ButtonGroup — props the component does not have, and never had. Found by the registry gate’s props-table rule.

Separator and spacer

Two pieces ship with this install command and neither was named on this page.

• ToolbarSeparator draws the rule between groups and is aria-hidden: it is a visual boundary, and the grouping it depicts is carried for everyone else by the role="group" and its label.
• ToolbarSpacer pushes what follows to the far end of the bar. It uses a logical margin, so in a right-to-left layout “the far end” mirrors rather than staying on the side an English reader expects.
• Neither is focusable and neither is a control. A separator that can be tabbed to is a tab stop that does nothing, which is the cost of building furniture out of buttons.

Related

• Button — hierarchy, disabled reasoning, target sizes.
• Menu — where overflow goes, and why split buttons are banned for commits.
• Data grid — selection semantics the toolbar reports.
• Acknowledge & escalate — why bulk acknowledgement is absent.
• Spacing — the group gap that carries the meaning.