Toolbar

A container for groups of tool controls: role="toolbar" + aria-label, Tab enters and arrow keys move between controls (roving tabindex — only the current item is focused). Ships with three companion widgets — toggle group, separator, input — plus vertical layout, loop toggle, whole-bar disabled, size steps, overflow collapse and attached look.

Basic usage (native buttons)

Basic usage (native buttons)

Example

Toggle group (editor scenario)

oas-toolbar-toggle is the toolbar's toggle-group widget: single-select (default, toggle semantics (aria-pressed), not radio — mutually exclusive, clicking the selected item does nothing) and multiple-select (multiple, each item toggles independently). value is controlled (string for single / JSON array string for multiple); clicks emit oas-change. Use a multiple group for bold/italic/underline and a single group for alignment — the core editor toolbar shape.

Toggle group (bold/italic + alignment)

Style: bold, underline | Align: left

Example

Declarative Child-Element Channel

Besides the items JSON, you can declare toggle-group options declaratively with <oas-toolbar-toggle-item> child elements (the items attribute takes precedence when explicitly set; otherwise child elements are parsed and converge into the same rendering path). The default slot text is the label; attributes map to the ToolbarToggleItem fields: value / disabled. Child additions, removals, attribute and text changes re-render automatically (MutationObserver); aria-pressed single/multiple semantics are identical to the items channel, and toolbar integration (overflow collapse, arrow-key navigation) is unaffected.

Toggle group declarative child elements

BoldItalicUnderlineAlign leftAlign centerAlign right (disabled)Add one dynamicallyStyle: bold | Align: left

Example

Separator widget

oas-toolbar-separator replaces the old oas-divider + data-toolbar-ignore combo: it sets role="separator" automatically, is excluded from roving navigation, and its line direction follows the toolbar orientation (vertical line inside a horizontal toolbar, horizontal line inside a vertical one).

oas-button + separator

CutCopyPasteUndoRedo

Example

Vertical toolbar

orientation="vertical": aria-orientation="vertical" + vertical layout, ↑/↓ navigate along the axis (←/→ still work); the separator becomes a horizontal line.

Vertical toolbar

Example

Loop navigation toggle

loop is on by default (arrow keys wrap around the ends); with loop="false" navigation stops at the ends.

loop=false no wrap

Example

Size steps

size: small / medium (default) / large. Affects toolbar spacing, native buttons and the built-in widgets (toggle group / input follow automatically).

size steps

Example

Whole-bar disabled

disabled disables the whole toolbar (aria-disabled + inert, items skip roving); adding focusable-when-disabled keeps items focusable (aria-disabled, clicks are blocked — handy for tooltips explaining why).

Whole-bar disabled

Example

Disabled items

Buttons with disabled / aria-disabled are skipped by arrow-key navigation (roving skips them).

Disabled items

Example

Link item

a[href] items join roving automatically and get part="link" (unified link styling and focus ring).

Link item

Help center

Example

Far-aligned group

Add data-toolbar-far to an item: everything from that item onward is pushed to the far end (right-aligned in a horizontal toolbar, bottom-aligned in a vertical one) — handy for "primary actions left, settings/help right".

Far-aligned group

Example

start / end named slots

slot="start" content renders at the front of the toolbar, slot="end" at the tail (visual order: start → default → end; roving and overflow collapse follow this order). Prefer named slots for grouping; data-toolbar-far remains for backward compatibility (pushes an item to the far end — semantically close to the end slot), new code should prefer the end slot.

start / end slots

Example

Toolbar input widget

oas-toolbar-input: joins roving as a single tab stop (composite special case — while focus is inside the input, arrow keys are consumed by text editing; Tab leaves and toolbar navigation continues). oas-input fires while typing, oas-change on Enter/blur commit.

Toolbar input

input: -

Example

Overflow collapse (narrow container)

When the container is too narrow, overflowing items are folded into a "···" popup (ResizeObserver watches the width; click "···" to open mirrored items, clicking a mirror dispatches to the original control; the "···" highlights when a selected value is folded inside). Try shrinking the container below.

Overflow collapse

Example

Attached look (is-attached)

is-attached: containerized toolbar appearance (border + background + padding), nice when mounted next to another toolbar/panel.

is-attached

Example

Filter pill bar (oas-scope-bar)

oas-scope-bar is a filter pill row: a row of clickable pills where the selected one is shown with a low-opacity primary "active fill". Single-select (default, toggle semantics (aria-pressed), not radio — mutually exclusive, clicking the selected pill does nothing) or multiple (each pill toggles independently); value is controlled (string for single / JSON array string for multiple), clicks emit oas-change. label provides the accessible group name (the aria-label of role="group"). It works standalone or inside an oas-toolbar as one tab stop (internal arrow keys are self-managed and do not disturb toolbar roving).

Filter pill bar (single-select)

scope: all

Example

Filter pill bar (multiple-select)

scope: design, code

Example

Paired with oas-toolbar

Example

API

oas-toolbar

Attributes

Attribute	Description	Type	Default
disabled	Disable the whole toolbar (aria-disabled + inert; items skip roving)	boolean	—
focusable-when-disabled	Keep items focusable while disabled (aria-disabled + clicks blocked; handy for tooltips explaining why)	boolean	—
loop	Wrap-around arrow navigation: on by default; false stops at the ends	string	—
orientation	Layout direction: horizontal (default) / vertical (arrow navigation follows the axis; separator becomes a horizontal line)	string	horizontal
size	Size step: small / medium (default) / large	string	—

Slots

Name	Description
default	Toolbar controls: buttons / oas-button / toggle group / input / links / separators, etc.
end	Content at the tail of the toolbar (rendered after the default content; participates in roving and overflow collapse; semantically close to data-toolbar-far, prefer this slot for new code)
start	Content at the front of the toolbar (rendered before the default content; participates in roving and overflow collapse)

oas-toolbar-toggle

Attributes

Attribute	Description	Type	Default
disabled	Disable the whole group	boolean	—
items	Options JSON (property assignment reflects one-way to the attribute)	ToolbarToggleItem[] | string	[]
multiple	Multiple-select mode (each item toggles independently)	boolean	—
size	Size step (small/medium/large); defaults to the nearest oas-toolbar's size	string	—
value	Current value: string for single-select; JSON array string for multiple-select	string	—

Events

Event	Description
oas-change	Toggle, detail: { value: string | string[] }

oas-toolbar-input

Attributes

Attribute	Description	Type	Default
disabled	Disabled	boolean	—
placeholder	Placeholder text	string	—
size	Size step (small/medium/large); defaults to the nearest oas-toolbar's size	string	—
value	Preset value (controlled entry; events do not write back, listen to update)	string	—

Events

Event	Description
oas-change	Committed on Enter or blur, detail: { value }
oas-input	While typing, detail: { value }

CSS Variables

CSS Variable	Default
--oas-toolbar-input-width	120px

oas-toolbar-toggle-item

Attributes

Attribute	Description	Type	Default
disabled	Disable this item (not clickable; skipped by arrow keys)	—	—
value	Item value (data-carrier field of the declarative child-element channel)	—	—

Slots

Name	Description
default	Button label (default slot text)

oas-scope-bar

Attributes

Attribute	Description	Type	Default
disabled	Disable the whole bar (combined with the nearest oas-toolbar's disabled)	boolean	—
items	Options JSON (property assignment reflects one-way to the attribute)	ScopeBarItem[] | string	[]
label	Accessible group name (the aria-label of role="group"; supplied by the host per language)	string	—
multiple	Multiple-select mode (each pill toggles independently)	boolean	—
size	Size step (small/medium/large); defaults to the nearest oas-toolbar's size	string	—
value	Current value: string for single-select; JSON array string for multiple-select	string	—

Events

Event	Description
oas-change	Toggle, detail: { value: string | string[] }

• The host has role="toolbar" + aria-orientation; aria-label comes from the locale key (toolbar.label)
• Children that join roving: native controls (button/input/select/textarea/a[href]), interactive roles, custom elements (tag contains -); oas-toolbar-separator, data-toolbar-ignore and aria-hidden are excluded, disabled/aria-disabled are skipped automatically (aria-disabled items stay focusable in focusable-when-disabled mode)
• Keyboard: Tab enters (only the current item is tab-reachable), ←/→ (or ↑/↓) moves between controls, Home/End jumps to the first/last; while focus is inside the toggle group/input the arrow keys belong to the widget (Tab leaves and toolbar navigation continues)
• Overflow collapse: ResizeObserver tracks width; overflowing items fold into the "···" panel (horizontal only)