Toolbar

A horizontal action bar with named slots for search, filters, and action buttons. Supports sticky positioning, density variants, and flexible alignment.

Basic Usage

Simple toolbar

<x-wirekit::toolbar aria-label="Page actions">
    <x-wirekit::button size="sm">Export</x-wirekit::button>
    <x-wirekit::button size="sm" intent="primary">Create</x-wirekit::button>
</x-wirekit::toolbar>

Three-Zone Layout

Use named slots for structured toolbar regions:

Leading + filters + trailing

Active Archived

<x-wirekit::toolbar aria-label="Search and filter">
    <x-slot:leading>
        <x-wirekit::input aria-label="Search" type="search" placeholder="Search..." />
    </x-slot:leading>
    <x-slot:filters>
        <x-wirekit::badge>Active</x-wirekit::badge>
        <x-wirekit::badge intent="neutral">Archived</x-wirekit::badge>
    </x-slot:filters>
    <x-slot:trailing>
        <x-wirekit::button size="sm" intent="primary">New Item</x-wirekit::button>
    </x-slot:trailing>
</x-wirekit::toolbar>

Pin the toolbar to the top of a scrollable container. The preview wraps the toolbar plus a tall body in an overflow-scrolling box so the sticky behavior is observable without scrolling the outer page — scroll inside the box to watch the toolbar stay anchored at the top.

A field that takes the focus inside the container, or a fragment link's target, comes to rest below the sticky toolbar rather than under it (keeping the focus clear of a pinned bar).

Sticky toolbar pinned at top of scrollable container

Scroll this panel — the toolbar above stays pinned to the top while the body below scrolls. The sticky-pin uses native CSS position: sticky against the nearest scrolling ancestor (this overflow:auto wrapper), so no JS scroll listener is needed and the behavior holds at any viewport.

For the sticky to work the toolbar's parent must be either a scrolling container (this wrapper) or the document root. Mounting a sticky toolbar inside a parent with overflow: hidden or a flex layout that constrains height will pin it against the wrong ancestor — opt out by setting :sticky="false" when the toolbar lives inside a non-scrolling card.

Filler content to demonstrate the scroll. Each paragraph adds vertical real estate that pushes the bottom of the panel beyond the visible viewport. The toolbar tracks the top boundary as the reader scrolls.

Use sticky toolbars for primary actions in long-form admin panels (Save / Discard for an edit screen, Filter / Sort for a long results list, Compose / Reply for a mail thread). Avoid for read-only contexts where the toolbar's affordances are unrelated to the body content.

Combine with density="compact" to minimize the height the sticky toolbar reserves at the top of the scrollable region — useful when vertical space is tight.

The sticky pin respects the container's top offset, so if the scrolling ancestor itself has padding-top, the toolbar pins below the padding rather than against the raw scroll edge.

More filler. The sticky should now be visibly anchored. Scroll back to the top to see the toolbar return to its document-flow position; the pinning is purely a scroll-position behavior, not a layout shift.

End of the scrollable body. The toolbar above is the last thing you see at the top regardless of how far down you scroll.

<x-wirekit::scroll-area max-height="16rem" label="Sticky toolbar demo" style="height: 16rem; border: 1px solid var(--color-wk-border); border-radius: var(--radius-wk-md);">
    <x-wirekit::toolbar :sticky="true" aria-label="Sticky actions">
        <x-wirekit::button size="sm">Save</x-wirekit::button>
        <x-wirekit::button size="sm" intent="danger">Discard</x-wirekit::button>
    </x-wirekit::toolbar>
    <div style="padding: 1rem; font-family: var(--font-wk-sans); color: var(--color-wk-text); display: flex; flex-direction: column; gap: 0.75rem;">
        <p>Scroll this panel — the toolbar above stays pinned to the top while the body below scrolls. The sticky-pin uses native CSS <code>position: sticky</code> against the nearest scrolling ancestor (this overflow:auto wrapper), so no JS scroll listener is needed and the behavior holds at any viewport.</p>
        <p>For the sticky to work the toolbar's parent must be either a scrolling container (this wrapper) or the document root. Mounting a sticky toolbar inside a parent with <code>overflow: hidden</code> or a flex layout that constrains height will pin it against the wrong ancestor — opt out by setting <code>:sticky="false"</code> when the toolbar lives inside a non-scrolling card.</p>
        <p>Filler content to demonstrate the scroll. Each paragraph adds vertical real estate that pushes the bottom of the panel beyond the visible viewport. The toolbar tracks the top boundary as the reader scrolls.</p>
        <p>Use sticky toolbars for primary actions in long-form admin panels (Save / Discard for an edit screen, Filter / Sort for a long results list, Compose / Reply for a mail thread). Avoid for read-only contexts where the toolbar's affordances are unrelated to the body content.</p>
        <p>Combine with <code>density="compact"</code> to minimize the height the sticky toolbar reserves at the top of the scrollable region — useful when vertical space is tight.</p>
        <p>The sticky pin respects the container's <code>top</code> offset, so if the scrolling ancestor itself has padding-top, the toolbar pins below the padding rather than against the raw scroll edge.</p>
        <p>More filler. The sticky should now be visibly anchored. Scroll back to the top to see the toolbar return to its document-flow position; the pinning is purely a scroll-position behavior, not a layout shift.</p>
        <p>End of the scrollable body. The toolbar above is the last thing you see at the top regardless of how far down you scroll.</p>
    </div>
</x-wirekit::scroll-area>

Density Variants

Compact vs comfortable density

<x-wirekit::stack gap="md">
    <x-wirekit::toolbar density="compact" aria-label="Compact toolbar">
        <x-wirekit::button size="sm">Action A</x-wirekit::button>
        <x-wirekit::button size="sm">Action B</x-wirekit::button>
    </x-wirekit::toolbar>
    <x-wirekit::toolbar density="comfortable" aria-label="Comfortable toolbar">
        <x-wirekit::button size="sm">Action A</x-wirekit::button>
        <x-wirekit::button size="sm">Action B</x-wirekit::button>
    </x-wirekit::toolbar>
</x-wirekit::stack>

Alignment

Alignment variants

<x-wirekit::stack gap="md">
    <x-wirekit::toolbar align="start" aria-label="Start-aligned">
        <x-wirekit::button size="sm">Left</x-wirekit::button>
    </x-wirekit::toolbar>
    <x-wirekit::toolbar align="end" aria-label="End-aligned">
        <x-wirekit::button size="sm">Right</x-wirekit::button>
    </x-wirekit::toolbar>
    <x-wirekit::toolbar align="between" aria-label="Space-between">
        <x-slot:leading>
            <x-wirekit::button size="sm">Left</x-wirekit::button>
        </x-slot:leading>
        <x-slot:trailing>
            <x-wirekit::button size="sm">Right</x-wirekit::button>
        </x-slot:trailing>
    </x-wirekit::toolbar>
</x-wirekit::stack>

Props

Prop	Type	Default	Description
`sticky`	`bool`	`false`	Pin to top of scroll container
`density`	`string`	`'comfortable'`	Padding density: `comfortable` or `compact`
`align`	`string`	`'between'`	Content alignment: `between`, `start`, `end`
`aria-label`	`string`	`null`	Accessible label for the toolbar
`scope`	string\|null	`null`	Scoped personalization name

Slots

Slot	Description
`leading`	Left region (search, primary controls)
`filters`	Center region (filter chips, badges)
`trailing`	Right region (action buttons)
default	Falls back to trailing region

Accessibility

role="group" on the root element — a related set of controls, each reached with Tab
Pass aria-label so the group is announced with a purpose rather than as an unnamed one
Responsive: wraps on narrow viewports via flex-wrap

Keyboard Interaction

This component is a layout wrapper. Keyboard interaction is delegated to its children: Tab moves to each control in turn, and every control keeps the keys it already handles.

It deliberately does not render role="toolbar". That role is a promise about the keyboard — one tab stop for the whole bar, arrow keys moving between the controls inside it, Home / End to the ends — and this component binds no keys, so the promise would be one it cannot keep. It also could not keep it in general: the leading slot is meant for a search field, where Left / Right belong to the text.

When you want that model, reach for a component that owns its own controls and can implement it — the editor's command bar is one.

Pitfalls

Don't reach for this when you need arrow-key navigation between the controls. It is chrome: it lays the controls out and names the group. Nothing here changes how any of them is reached.

Design Tokens

The Toolbar is a layout primitive — it composes its inner controls (search inputs, buttons, badges) and inherits their tokens. Only the wrapper itself reaches for tokens directly:

Token	Used for
`--font-wk-sans`	Toolbar font family
`--color-wk-bg`	Toolbar background

For control-level tokens see Input, Button, and Badge.

Toolbar

Was this page helpful?