Toolbar

A row of buttons, links, and selectable groups that arrow keys move between.

Installation

pnpm dlx @mielui/svelte add toolbar

Usage

Root holds one keyboard collection of Buttons, Links, Separators, and Groups of Items. Tab enters the toolbar once and arrow keys move along it, skipping disabled controls and wrapping at the ends unless loop is false. Give Root an aria-label or aria-labelledby, and label every icon-only control.

<script lang="ts">
    import * as Toolbar from '@mielui/svelte/components/toolbar';

    let formats = $state<string[]>([]);

    function clear() {
        formats = [];
    }
</script>

<Toolbar.Root aria-label="Text formatting">
    <Toolbar.Group type="multiple" bind:value={formats} aria-label="Text styles">
        <Toolbar.Item value="bold">Bold</Toolbar.Item>
        <Toolbar.Item value="italic">Italic</Toolbar.Item>
    </Toolbar.Group>
    <Toolbar.Separator />
    <Toolbar.Button onclick={clear}>Clear</Toolbar.Button>
    <Toolbar.Link href="/docs">Help</Toolbar.Link>
</Toolbar.Root>

Use Items inside a Group for choices that stay selected: type="single" with a string value, or type="multiple" with an array. Use Button for one-off actions such as Clear. Separator runs perpendicular to the toolbar; set decorative when it is only visual. Every part takes class and bind:element. Use Items for selections instead of nesting a ToggleGroup, which would add a second keyboard collection.

The package also exports a plain Toolbar: a styled element with the toolbar role and arrow-key navigation between whatever buttons you put in it.

Examples

Design tools

Icon tools with shortcut tooltips sit beside zoom buttons, and a status line names the selected tool.

Move selected · 100% zoom

Depth

The default toolbar is a flat grey track with one hover wash that travels between keys. variant="depth" floats it on a raised shell with raised keys and recessed selections. Depth follows the shadow and motion settings of the theme.

Move selected · 100% zoom

Multiple selection

A note for the team.

API reference

Toolbar.Root

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
loop

boolean
Whether or not to loop through the toolbar items when navigating with the keyboard.
orientation

Orientation
The orientation of the toolbar. This determines how keyboard navigation will work within the toolbar.

Default 'horizontal'
variant

"default" | "depth"
depth gives the toolbar raised keys and a floating shell.

Default 'default'
element Bindable

HTMLDivElement | null
Bindable reference to the DOM element.

Default null

Toolbar.Button

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
disabled

boolean | null
Whether the button is disabled or not.
element Bindable

HTMLButtonElement | null
Bindable reference to the DOM element.

Default null

Toolbar.Group

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
disabled

boolean
Whether the toggle group is disabled or not.
type Required

"single" | "multiple"
single keeps one value. multiple allows several and makes value an array.
value Bindable

string | string[]
Selected tool, or an array in multiple mode. Bindable.
onValueChange

((value: string) => void) | ((value: string[]) => void)
Called with the new value when it changes.
element Bindable

HTMLDivElement | null
Bindable reference to the DOM element.

Default null

Toolbar.Item

children

Snippet<[ToggleGroupItemSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
disabled

boolean | null
Whether the toggle item is disabled or not.
value Required

string
The value of the toggle item.
element Bindable

HTMLButtonElement | null
Bindable reference to the DOM element.

Default null

Toolbar.Link

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
element Bindable

HTMLAnchorElement | null
Bindable reference to the DOM element.

Default null

Toolbar.Separator

id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
orientation

Orientation
The orientation of the separator.
decorative

boolean
Whether the separator is decorative and should be hidden from assistive technologies.
element Bindable

HTMLDivElement | null
Bindable reference to the DOM element.

Default null

Toolbar

Groups related controls.

class

(string & (ClassValue | null))
Classes added to the element.
children

Snippet<[]>
Content rendered inside.