Toolbar & button group

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 & popover.
• 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.

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

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

Implementation

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

// Scope is a required prop, not a convention. A toolbar that does not
// know what it acts on cannot label its actions.
<Toolbar
  label="ECG review actions"
  scope={{ kind: "recording", id: "ecg-14263800", display: "ECG 14:26:38" }}
  controls="waveform-region"
>
  <ButtonGroup label="Lead layout" value={layout} onChange={setLayout}>
    <ButtonGroup.Item value="12x1">12 × 1</ButtonGroup.Item>
    <ButtonGroup.Item value="3x4">3 × 4</ButtonGroup.Item>
  </ButtonGroup>
  <Toolbar.Separator />
  <Toolbar.Action onSelect={openCalipers}>Calipers</Toolbar.Action>
</Toolbar>

// A selection-scoped action must interpolate the count, so the label
// cannot silently disagree with the selection.
if (scope.kind === "selection" && !/\{count\}/.test(action.label)) {
  throw new Error("[Toolbar] selection-scoped actions must include {count} in the label.")
}

Related

• Button — hierarchy, disabled reasoning, target sizes.
• Menu & popover — 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.