Toolbar
newYour app's utility belt. A row or column of buttons, toggles, links and separators. One Tab gets you in, arrow keys do the rest.
Open Props in the corner of the example to try variant.
Installation
Usage
<script setup lang="ts">
import { Bold, Italic } from '@lucide/vue'
import { Toolbar, ToolbarButton, ToolbarSeparator, ToolbarToggleGroup, ToolbarToggleItem } from '@/components/ui/toolbar'
</script>
<template>
<Toolbar aria-label="Formatting">
<ToolbarToggleGroup type="multiple" size="icon-sm">
<ToolbarToggleItem value="bold" aria-label="Bold"><Bold /></ToolbarToggleItem>
<ToolbarToggleItem value="italic" aria-label="Italic"><Italic /></ToolbarToggleItem>
</ToolbarToggleGroup>
<ToolbarSeparator />
<ToolbarButton>Share</ToolbarButton>
</Toolbar>
</template>
Give it an aria-label so screen readers know what it's for.
ToolbarButton,ToolbarLink: a regular Button,ghost+neutralby defaultToolbarToggleGroup,ToolbarToggleItem: a ToggleGroup with gaps instead of joined edgesToolbarSeparator: a divider
Examples
Vertical
orientation="vertical" stacks the parts and the up and down arrows move focus. Toggle groups and separators follow.
Ghost
variant="ghost" drops the frame, for a row of buttons in a card or page header that still moves focus with the arrows.
Draft
API Reference
Every part accepts class, merged over its base classes.
Toolbar
| Prop | Default | Type and description |
|---|---|---|
| orientation | "horizontal" | DataOrientation
|
| dir | — | DirectionReading direction. In |
| loop | true | booleanLets the arrow keys wrap from the last part to the first. On by default. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the toolbar's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | "outline" | NonNullable<"outline" | "ghost" | null | undefined>
|
| Slot | Scope and description |
|---|---|
| default | {}The buttons, links, toggle groups and separators. |
ToolbarButton
| Prop | Default | Type and description |
|---|---|---|
| variant | "ghost" | "ghost" | "solid" | "soft" | "subtle" | "outline" | "link" | nullThe Button variant. |
| color | "neutral" | ButtonColorThe Button colour. |
| size | "sm" | ButtonSizeThe Button size. |
| disabled | — | booleanDisables the button and takes it out of the arrow-key order. |
| Slot | Scope and description |
|---|---|
| default | {}The button's content. |
ToolbarLink
| Prop | Default | Type and description |
|---|---|---|
| color | "neutral" | ButtonColorThe Button colour. |
| size | "sm" | ButtonSizeThe Button size. |
| Slot | Scope and description |
|---|---|
| default | {}The link's text. |
ToolbarSeparator
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the separator's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
ToolbarToggleGroup
| Prop | Default | Type and description |
|---|---|---|
| rovingFocus | — | booleanUnused inside a toolbar, which already moves focus with the arrow keys. |
| disabled | — | booleanDisables every item. |
| orientation | — | DataOrientationUnused inside a toolbar, which passes its own orientation down. |
| dir | — | DirectionReading direction. Inherits from the toolbar. |
| loop | — | booleanUnused inside a toolbar, which already wraps focus. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| name | — | stringSubmits the value with its form under this name. |
| required | — | booleanKeeps one item on in |
| type | — | SingleOrMultipleType
|
| modelValue | — | AcceptableValue | AcceptableValue[]The value of the item that is on, or the values in |
| defaultValue | — | AcceptableValue | AcceptableValue[]The item or items on at first when |
| variant | "ghost" | "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullThe Button variant of the items while off. |
| activeVariant | "soft" | "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullThe Toggle variant of the items while on. |
| color | "neutral" | ButtonColor | (string & {})The colour of the items while off. |
| activeColor | — | ButtonColor | (string & {})The colour of the items while on. Falls back to |
| size | "sm" | "sm" | "xs" | "md" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullThe Button size of the items. |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: AcceptableValue | AcceptableValue[]]Fires when an item turns on or off. |
| Slot | Scope and description |
|---|---|
| default | {}The items. Receives |
ToolbarToggleItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe value this item stands for. |
| disabled | — | booleanDisables this item alone. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the item's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | — | "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group's |
| activeVariant | — | "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group's |
| color | — | ButtonColor | (string & {})Overrides the group's |
| activeColor | — | ButtonColor | (string & {})Overrides the group's |
| size | — | "xs" | "sm" | "md" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullOverrides the group's |
| Slot | Scope and description |
|---|---|
| default | {}The item's content. |
Props
- orientation
"horizontal" DataOrientationhorizontallays the parts out in a row and the left and right arrows move focus;verticalstacks them and the up and down arrows move focus.- dir
DirectionReading direction. Inrtlthe arrows run the other way.- loop
true booleanLets the arrow keys wrap from the last part to the first. On by default.- asChild
booleanRender the single child instead of a wrapper, merging the toolbar's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
"outline" NonNullable<"outline" | "ghost" | null | undefined>outlineframes the toolbar with a border, a radius and padding;ghostis a bare row.
Slots
- default
{}The buttons, links, toggle groups and separators.
Props
- variant
"ghost" "ghost" | "solid" | "soft" | "subtle" | "outline" | "link" | nullThe Button variant.ghostby default.- color
"neutral" ButtonColorThe Button colour.neutralby default.- size
"sm" ButtonSizeThe Button size.smby default; useicon-smfor an icon alone.- disabled
booleanDisables the button and takes it out of the arrow-key order.
Slots
- default
{}The button's content.
Props
- color
"neutral" ButtonColorThe Button colour.neutralby default.- size
"sm" ButtonSizeThe Button size.smby default.
Slots
- default
{}The link's text.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the separator's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Props
- rovingFocus
booleanUnused inside a toolbar, which already moves focus with the arrow keys.- disabled
booleanDisables every item.- orientation
DataOrientationUnused inside a toolbar, which passes its own orientation down.- dir
DirectionReading direction. Inherits from the toolbar.- loop
booleanUnused inside a toolbar, which already wraps focus.- asChild
booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- name
stringSubmits the value with its form under this name.- required
booleanKeeps one item on insinglemode.- type
SingleOrMultipleTypesinglekeeps one item on at a time andv-modelis a string;multiplelets several stay on andv-modelis an array.- modelValue
AcceptableValue | AcceptableValue[]The value of the item that is on, or the values inmultiplemode, bound withv-model.- defaultValue
AcceptableValue | AcceptableValue[]The item or items on at first whenv-modelis not used.- variant
"ghost" "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullThe Button variant of the items while off.ghostby default.- activeVariant
"soft" "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullThe Toggle variant of the items while on.softby default.- color
"neutral" ButtonColor | (string & {})The colour of the items while off.neutralby default.- activeColor
ButtonColor | (string & {})The colour of the items while on. Falls back tocolor.- size
"sm" "sm" | "xs" | "md" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullThe Button size of the items.smby default; useicon-smfor icons alone.
Emits
- update:modelValue
[payload: AcceptableValue | AcceptableValue[]]Fires when an item turns on or off.
Slots
- default
{}The items. ReceivesmodelValue.
Props
- value*
AcceptableValueThe value this item stands for.- disabled
booleanDisables this item alone.- asChild
booleanRender the single child instead of a wrapper, merging the item's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
"solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group'svariantfor this item.- activeVariant
"solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group'sactive-variantfor this item.- color
ButtonColor | (string & {})Overrides the group'scolorfor this item.- activeColor
ButtonColor | (string & {})Overrides the group'sactive-colorfor this item.- size
"xs" | "sm" | "md" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullOverrides the group'ssizefor this item.
Slots
- default
{}The item's content.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| toolbar | data-variant, aria-orientation | The root, a role="toolbar". |
| toolbar-button | data-variant, data-color, data-size, data-orientation | A Button in the focus order. |
| toolbar-link | data-variant, data-color, data-size, data-orientation | A link Button in the focus order. |
| toolbar-separator | data-orientation | The line, carrying the toolbar's orientation. |
| toolbar-toggle-group | data-orientation, data-size | A role="group" of toggle items. |
| toolbar-toggle-item | data-state, data-variant, data-color, data-size, data-orientation | A toggle item in the focus order. |
Keyboard
| Key | Action |
|---|---|
| Tab | Moves focus into the toolbar, onto the last focused part, and out again. |
| ArrowLeft / ArrowRight | Moves focus between the parts of a horizontal toolbar, wrapping around. |
| ArrowUp / ArrowDown | Moves focus between the parts of a vertical toolbar, wrapping around. |
| Home / End | Moves focus to the first or last part. |
| Space / Enter | Activates the focused button, link or toggle. |