ChromVoid UIKit

Container of interactive elements that provides a single tab stop and arrow-key navigation between items, with separator support and focus memory.

Headless: createToolbar

Usage

View source

html

<div class="toolbar-demo-shell" data-demo="toolbar">
  <section class="toolbar-demo-hero" aria-labelledby="toolbar-demo-title">
    <div class="toolbar-demo-copy">
      <span class="toolbar-demo-kicker">Composite command surface</span>
      <h3 id="toolbar-demo-title">Use toolbar when Tab should enter once and arrows move between tools.</h3>
      <p>
        Toolbar gives a cluster of peer commands one accessible surface:
        <code>role="toolbar"</code>, roving <code>tabindex</code>, arrow-key movement, separators, focus
        memory, and a controlled <code>value</code> for the active item.
      </p>
    </div>

    <dl class="toolbar-demo-metrics" aria-label="Toolbar behavior summary">
      <div>
        <dt>Tab stop</dt>
        <dd>one</dd>
      </div>
      <div>
        <dt>Keys</dt>
        <dd>arrows / Home / End</dd>
      </div>
      <div>
        <dt>State</dt>
        <dd>value + cv-change</dd>
      </div>
    </dl>
  </section>

  <section class="toolbar-demo-workbench" aria-labelledby="toolbar-demo-workbench-title">
    <div class="toolbar-demo-section-header">
      <span class="toolbar-demo-kicker">Record command strip</span>
      <h4 id="toolbar-demo-workbench-title">
        One toolbar can expose editing, inspection, and export tools without adding extra Tab stops
      </h4>
    </div>

    <div class="toolbar-demo-surface">
      <header class="toolbar-demo-surface-header">
        <div>
          <span class="toolbar-demo-label">Vault record</span>
          <strong>Border checkpoint profile</strong>
        </div>
        <output class="toolbar-demo-state" data-toolbar-active aria-live="polite">Command strip: Mask</output>
      </header>

      <cv-toolbar class="toolbar-demo-command-strip" value="item-1" wrap aria-label="Vault record tools">
        <cv-toolbar-item value="item-1">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">M</span>
            <span>Mask</span>
          </span>
        </cv-toolbar-item>
        <cv-toolbar-item value="item-2">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">R</span>
            <span>Reveal</span>
          </span>
        </cv-toolbar-item>
        <cv-toolbar-item value="item-3">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">C</span>
            <span>Copy</span>
          </span>
        </cv-toolbar-item>
        <cv-toolbar-separator></cv-toolbar-separator>
        <cv-toolbar-item value="item-4">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">A</span>
            <span>Audit</span>
          </span>
        </cv-toolbar-item>
        <cv-toolbar-item value="item-5" disabled>
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">E</span>
            <span>Export</span>
          </span>
        </cv-toolbar-item>
      </cv-toolbar>

      <div class="toolbar-demo-record" aria-label="Selected record preview">
        <div>
          <span>Surface</span>
          <strong>Travel profile</strong>
        </div>
        <div>
          <span>Visible state</span>
          <strong>masked</strong>
        </div>
        <div>
          <span>Audit trail</span>
          <strong>ready</strong>
        </div>
      </div>

      <output class="toolbar-demo-log" data-toolbar-log aria-live="polite">
        cv-change will report the active tool after keyboard or pointer movement.
      </output>
    </div>
  </section>

  <section class="toolbar-demo-split" aria-labelledby="toolbar-demo-rail-title">
    <div class="toolbar-demo-rail-panel">
      <div class="toolbar-demo-section-header">
        <span class="toolbar-demo-kicker">Vertical tool rail</span>
        <h4 id="toolbar-demo-rail-title">Use orientation for side tools and dense editors</h4>
      </div>

      <cv-toolbar
        class="toolbar-demo-rail"
        value="item-1"
        orientation="vertical"
        aria-label="Inspector tools"
      >
        <cv-toolbar-item value="item-1">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">I</span>
            <span>Inspect</span>
          </span>
        </cv-toolbar-item>
        <cv-toolbar-item value="item-2">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">H</span>
            <span>History</span>
          </span>
        </cv-toolbar-item>
        <cv-toolbar-separator></cv-toolbar-separator>
        <cv-toolbar-item value="item-3">
          <span class="toolbar-demo-item">
            <span class="toolbar-demo-glyph" aria-hidden="true">P</span>
            <span>Policy</span>
          </span>
        </cv-toolbar-item>
      </cv-toolbar>
    </div>

    <div class="toolbar-demo-boundary">
      <span class="toolbar-demo-kicker">Boundary</span>
      <h4>Toolbar is not a button group.</h4>
      <div class="toolbar-demo-boundary-grid">
        <div>
          <span class="toolbar-demo-label">button-group</span>
          <cv-button-group attached aria-label="Record actions">
            <cv-button size="small" variant="primary">Unlock</cv-button>
            <cv-button size="small">Lock</cv-button>
            <cv-button size="small" variant="danger">Wipe</cv-button>
          </cv-button-group>
          <p>Use for independent buttons that stay normal buttons in the Tab order.</p>
        </div>

        <div>
          <span class="toolbar-demo-label">toolbar</span>
          <p>
            Use for peer tools inside one command surface, where Tab enters the surface once and arrows move
            between items.
          </p>
        </div>
      </div>
    </div>
  </section>
</div>

<script>
  document.querySelectorAll('.toolbar-demo-shell[data-demo="toolbar"]:not([data-ready])').forEach((shell) => {
    shell.dataset.ready = 'true'
    const activeOutput = shell.querySelector('[data-toolbar-active]')
    const logOutput = shell.querySelector('[data-toolbar-log]')

    const labelForValue = (toolbar, value) => {
      const item = Array.from(toolbar.querySelectorAll('cv-toolbar-item')).find(
        (candidate) => candidate.value === value || candidate.getAttribute('value') === value,
      )
      return item?.querySelector('.toolbar-demo-item span:last-child')?.textContent?.trim() || value
    }

    const bindToolbar = (selector, label) => {
      const toolbar = shell.querySelector(selector)
      if (!toolbar) return

      toolbar.addEventListener('cv-change', (event) => {
        const value = event.detail?.activeId || toolbar.getAttribute('value') || 'none'
        const readableValue = labelForValue(toolbar, value)
        if (activeOutput) {
          activeOutput.textContent = `${label}: ${readableValue}`
        }
        if (logOutput) {
          logOutput.textContent = `cv-change -> activeId "${value}" (${readableValue})`
        }
      })
    }

    bindToolbar('.toolbar-demo-command-strip', 'Command strip')
    bindToolbar('.toolbar-demo-rail', 'Inspector rail')
  })
</script>

Anatomy

<cv-toolbar> (host)
└── <div part="base" role="toolbar" aria-orientation="…">
    └── <slot>                         ← accepts <cv-toolbar-item> and <cv-toolbar-separator> children

Attributes

Attribute	Type	Default	Description
`value`	String	`""`	Active item value (reflects `activeId` from headless state)
`orientation`	String	`"horizontal"`	Navigation axis: `horizontal` \| `vertical`
`wrap`	Boolean	`true`	Whether arrow navigation wraps from last to first and vice versa. When `false`, clamps at boundaries.
`aria-label`	String	`""`	Accessible label for the toolbar

Slots

Slot	Description
`(default)`	`<cv-toolbar-item>` and `<cv-toolbar-separator>` children

CSS Parts

Part	Element	Description
`base`	`<div>`	Root layout container with `role="toolbar"`

CSS Custom Properties

Property	Default	Description
`--cv-toolbar-gap`	`var(--cv-space-1, 4px)`	Spacing between toolbar children
`--cv-toolbar-padding`	`var(--cv-space-1, 4px)`	Internal padding of the toolbar container
`--cv-toolbar-border-radius`	`var(--cv-radius-md, 10px)`	Border radius of the toolbar container

Additionally, component styles depend on theme tokens through fallback values:

Theme Property	Default	Description
`--cv-color-border`	`#2a3245`	Toolbar border color
`--cv-color-surface`	`#141923`	Toolbar background color
`--cv-space-1`	`4px`	Gap and padding fallback
`--cv-radius-md`	`10px`	Border radius fallback

Visual States

Host selector	Description
`:host([orientation="vertical"])`	Flex direction switches to column; items stretch to fill width

Events

Event	Detail	Description
`cv-input`	`{activeId: string \| null}`	Fires on any user-driven active item change (arrow keys, click, focus)
`cv-change`	`{activeId: string \| null}`	Fires when active item commits (same detail as `cv-input`; both fire together on navigation)

Both cv-input and cv-change fire when user interaction changes the active item. Programmatic value attribute changes that result in a headless state update also dispatch these events.

Reactive State Mapping

cv-toolbar is a visual adapter over headless createToolbar.

UIKit Property to Headless Binding

UIKit Property	Direction	Headless Binding
`value`	attr -> action	`actions.setActive(value)` when `value` attribute changes
`orientation`	attr -> option	passed as `orientation` in `createToolbar(options)`
`wrap`	attr -> option	passed as `wrap` in `createToolbar(options)`
`aria-label`	attr -> option	passed as `ariaLabel` in `createToolbar(options)`

Headless State to DOM Reflection

Headless State	Direction	DOM Reflection
`state.activeId()`	state -> attr	`cv-toolbar[value]` host attribute
`state.activeId()`	state -> attr	`cv-toolbar-item[active]` boolean attribute on the active item element
`state.activeId()`	state -> prop	`cv-toolbar-item.tabIndex` set to `0` for active, `-1` for others

Headless Actions Called

Action	UIKit Trigger
`actions.setActive(id)`	Item receives focus or click; also called when `value` attribute changes
`actions.handleKeyDown(event)`	`keydown` event on the toolbar root `[part="base"]`
`actions.handleToolbarFocus()`	`focusin` event on toolbar root when toolbar was not previously focused (re-entry detection)
`actions.handleToolbarBlur()`	`focusout` event on toolbar root when `relatedTarget` is outside the toolbar (full blur detection)

Headless Contracts Spread

Contract	UIKit Target
`contracts.getRootProps()`	Spread onto the `[part="base"]` element (`id`, `role`, `aria-orientation`, `aria-label`)
`contracts.getItemProps(id)`	Spread onto each `cv-toolbar-item` element (`id`, `tabindex`, `aria-disabled`, `data-active`). The `onFocus` callback is bound to the element's `focus` event.
`contracts.getSeparatorProps(id)`	Spread onto each `cv-toolbar-separator` element (`id`, `role`, `aria-orientation`)

UIKit-Only Concerns (Not in Headless)

Focus management DOM calls: Calling .focus() on the DOM element matching activeId after keyboard navigation. Headless sets state; UIKit moves DOM focus.
Focus-in/focus-out tracking: UIKit must detect toolbar entry vs. internal focus moves (e.g., using a hasFocus flag updated on focusin/focusout with relatedTarget checks).
Separator rendering: Visual appearance of separators (line style, thickness, spacing) is a UIKit concern. Headless only provides ARIA props.
Slot change handling: Rebuilding the headless model when children are added or removed via slotchange.
cv-input / cv-change events: Custom DOM events dispatched by the UIKit wrapper, not part of the headless model.

UIKit does not own navigation or focus-memory logic; headless state is the source of truth.

Keyboard Interaction

Key	Horizontal	Vertical
`ArrowRight`	Move to next item	—
`ArrowLeft`	Move to previous item	—
`ArrowDown`	—	Move to next item
`ArrowUp`	—	Move to previous item
`Home`	Move to first item	Move to first item
`End`	Move to last item	Move to last item

Disabled items and separators are skipped during keyboard navigation.
When wrap is true (default), navigation wraps from last to first and vice versa.
When wrap is false, navigation clamps at boundaries (first/last item).
Roving tabindex: only the active item has tabindex="0"; all others have tabindex="-1".
Focus memory: re-entering the toolbar via Tab restores focus to the last-active item.

Child Elements

Interactive element within a toolbar that participates in roving tabindex navigation.

Anatomy

<cv-toolbar-item> (host)
└── <div part="base">
    └── <slot>

Attributes

Attribute	Type	Default	Description
`value`	String	`""`	Unique identifier for this item. Auto-generated as `item-{n}` if empty.
`disabled`	Boolean	`false`	Prevents this item from receiving focus via keyboard navigation
`active`	Boolean	`false`	Whether this item is the current roving-focus target (managed by parent)

Slots

Slot	Description
`(default)`	Item content (text, icon, or any inline content)

CSS Parts

Part	Element	Description
`base`	`<div>`	Root interactive wrapper

CSS Custom Properties

Property	Default	Description
`--cv-toolbar-item-min-height`	`32px`	Minimum block size of the item
`--cv-toolbar-item-padding-inline`	`var(--cv-space-3, 12px)`	Horizontal padding
`--cv-toolbar-item-border-radius`	`var(--cv-radius-sm, 6px)`	Border radius

Additionally, component styles depend on theme tokens through fallback values:

Theme Property	Default	Description
`--cv-color-border`	`#2a3245`	Item border color
`--cv-color-surface`	`#141923`	Item background color
`--cv-color-text`	`#e8ecf6`	Item text color
`--cv-color-primary`	`#65d7ff`	Active state accent color
`--cv-duration-fast`	`120ms`	Transition duration
`--cv-easing-standard`	`ease`	Transition timing function

Visual States

Host selector	Description
`:host([active])`	Primary-tinted border and blended background using `--cv-color-primary`
`:host([disabled])`	Reduced opacity (`0.55`)
`:host(:focus-visible)`	Focus ring: `2px solid var(--cv-color-primary)` with `1px` offset

Non-interactive visual divider within a toolbar. Separators are skipped by keyboard navigation and cannot receive focus.

Anatomy

<cv-toolbar-separator> (host)
└── <div part="base" role="separator" aria-orientation="…">

The separator's aria-orientation is perpendicular to the toolbar's orientation: a horizontal toolbar renders vertical separators, and vice versa.

Attributes

Attribute	Type	Default	Description
`value`	String	`""`	Identifier used to match the separator in the headless item list

CSS Parts

Part	Element	Description
`base`	`<div>`	Separator line element with `role="separator"`

CSS Custom Properties

Property	Default	Description
`--cv-toolbar-separator-size`	`1px`	Thickness of the separator line
`--cv-toolbar-separator-color`	`var(--cv-color-border, #2a3245)`	Color of the separator line
`--cv-toolbar-separator-margin`	`var(--cv-space-1, 4px)`	Margin around the separator

Visual States

Host selector	Description
`:host`	In a horizontal toolbar: vertical line (`height: auto`, `width: --cv-toolbar-separator-size`). In a vertical toolbar: horizontal line (`width: auto`, `height: --cv-toolbar-separator-size`). Orientation is communicated via the parent spreading `getSeparatorProps`.

cv-toolbar ​

Usage ​

Anatomy ​

Attributes ​

Slots ​

CSS Parts ​

CSS Custom Properties ​

Visual States ​

Events ​

Reactive State Mapping ​

UIKit Property to Headless Binding ​

Headless State to DOM Reflection ​

Headless Actions Called ​

Headless Contracts Spread ​

UIKit-Only Concerns (Not in Headless) ​

Keyboard Interaction ​

Child Elements ​

cv-toolbar-item ​

Anatomy ​

Attributes ​

Slots ​

CSS Parts ​

CSS Custom Properties ​

Visual States ​

cv-toolbar-separator ​

Anatomy ​

Attributes ​

CSS Parts ​

CSS Custom Properties ​

Visual States ​

cv-toolbar

Usage

Anatomy

Attributes

Slots

CSS Parts

CSS Custom Properties

Visual States

Events

Reactive State Mapping

UIKit Property to Headless Binding

Headless State to DOM Reflection

Headless Actions Called

Headless Contracts Spread

UIKit-Only Concerns (Not in Headless)

Keyboard Interaction

Child Elements

cv-toolbar-item

Anatomy

Attributes

Slots

CSS Parts

CSS Custom Properties

Visual States

cv-toolbar-separator

Anatomy

Attributes

CSS Parts

CSS Custom Properties

Visual States