Skip to content

Toolbar

A row of buttons and toggles that is one tab stop, with arrow keys and grouped separators.

<div class="cap-toolbar" role="toolbar" aria-label="Draft" data-cap="toolbar" id="tb-draft">
  <button type="button" class="cap-btn">Save</button>
  <button type="button" class="cap-btn">Preview</button>
  <button type="button" class="cap-btn" disabled>Publish</button>
  <span class="cap-toolbar-sep" role="separator" aria-orientation="vertical"></span>
  <button type="button" class="cap-btn" aria-pressed="true" id="tb-wrap">Wrap lines</button>
  <button type="button" class="cap-btn" aria-pressed="false">Show changes</button>
  <a class="cap-btn" data-variant="quiet" href="#history">History</a>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/toolbar.css";
import { enhance } from "capsomer/behavior/toolbar";

enhance();

Usage

<div class="cap-toolbar" role="toolbar" aria-label="Draft" data-cap="toolbar">
  <button type="button" class="cap-btn">Save</button>
  <button type="button" class="cap-btn">Preview</button>
  <span class="cap-toolbar-sep" role="separator" aria-orientation="vertical"></span>
  <button type="button" class="cap-btn" aria-pressed="false">Show changes</button>
</div>

Examples

Right to left: Left arrow moves forward

<div dir="rtl" lang="ar">
  <div class="cap-toolbar" role="toolbar" aria-label="مسودة" data-cap="toolbar" id="tb-rtl">
    <button type="button" class="cap-btn">حفظ</button>
    <button type="button" class="cap-btn">معاينة</button>
    <button type="button" class="cap-btn" aria-pressed="false">التغييرات</button>
  </div>
</div>

Vertical, comfortable density

<div data-density="comfortable">
  <div class="cap-toolbar" role="toolbar" aria-label="Sites" aria-orientation="vertical" data-cap="toolbar" id="tb-vertical">
    <button type="button" class="cap-btn">Refresh all</button>
    <button type="button" class="cap-btn">Pause checks</button>
    <span class="cap-toolbar-sep" role="separator"></span>
    <button type="button" class="cap-btn" aria-pressed="true">Only failing</button>
  </div>
</div>

An editor's formatting bar, keeping the editor's focus

<div>
  <div class="cap-toolbar" role="toolbar" aria-label="Formatting" id="tb-editor">
    <button type="button" class="cap-btn" id="tb-bold">Bold</button>
    <button type="button" class="cap-btn">Italic</button>
  </div>
  <textarea class="cap-input" id="tb-editor-text" aria-label="Draft">Field notes from the spring survey.</textarea>
</div>

API reference

Functions

FunctionSignatureDoes
rovingIndex(key: string, at: number, count: number, axis?: "horizontal" | "vertical", rtl?: boolean): number | nullThe toolbar's behavior (WAI-ARIA Authoring Practices, Toolbar): the bar is one tab stop (a roving tabindex), Left and Right move between its controls (swapped right to left; Up and Down in a vertical bar), Home and End go to the ends, and the ends wrap. The control last focused keeps the stop. No framework; the markdown editor's toolbar uses it too. Which item an arrow, Home or End moves to in a roving group (APG toolbar and menu). It wraps.
attachToolbar(bar: HTMLElement, items?: string, options?: ToolbarOptions): () => void
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="toolbar"] under root not yet attached. Returns a function that detaches them all.

CSS variables

VariableDefault
--cap-btn-bgvar(--accent-soft)
--cap-btn-linevar(--accent)

Parts and data attributes

ClassIs
.cap-toolbarthe root
.cap-toolbar-sepa part
StateRead from
[aria-orientation="vertical"]an attribute
[aria-pressed="true"]an attribute

Accessibility

KeyDoes
TabEnters the bar at its one stop; the next Tab leaves it
Right arrow, Left arrowNext or previous control, wrapping (swapped right to left)
Down arrow, Up arrowThe same in a vertical bar
Home, EndThe first or the last control
Enter, SpaceRuns a button or flips a toggle button
  • role="toolbar" with aria-label (or aria-labelledby); a screen reader names the bar on entry.
  • A toggle button's state is aria-pressed, read out as pressed or not pressed; its name does not change.
  • Forced colors: a pressed toggle is drawn in Highlight, and the separator in CanvasText.