ToggleButtons
A row of mutually exclusive buttons, one of which is selected. Give it items, or compose
options with ToggleButtons.Item. Inside a
Field it takes its id (the field’s controlId), disabled,
state, aria-labelledby, and aria-describedby from there.
Built on bits-ui ToggleGroup.
<Field class="flex flex-col gap-1"> <Label>Units</Label> <ToggleButtons bind:value items={[{ value: 'mm', label: 'mm' }, { value: 'in', label: 'in' }]} /></Field>- One
valuefor the whole group, bindable. Options come fromitems, or fromToggleButtons.Itemchildren. - One option is always selected: clicking the selected option does not clear it.
- Takes
state,disabled, and its labelling from an enclosingField, or directly.errorsetsaria-invalid="true"on the group. - Arrow keys move focus between options without selecting. Enter or Space selects.
- Each option is a
role="radio"button inside arole="group", and the selected one carriesdata-state="on".
Anatomy
Section titled “Anatomy”Pass items for the common case, or compose the options yourself with ToggleButtons.Item when they need more than text.
<ToggleButtons items={[{ value: "…", label: "…" }]} />
<ToggleButtons> <ToggleButtons.Item value="…">content</ToggleButtons.Item> <ToggleButtons.Item value="…">content</ToggleButtons.Item></ToggleButtons>Two-way binding
Section titled “Two-way binding”bind:value on the group. The items need no binding of their own.
value: mm
Code
<script lang="ts"> import { ToggleButtons } from "@viamrobotics/prime-ui";
const items = [ { value: "mm", label: "mm" }, { value: "cm", label: "cm" }, { value: "in", label: "in" }, ];
let units = $state("mm");</script>
<div class="not-content"> <ToggleButtons bind:value={units} {items} aria-label="Units" />
<p class="mt-3 text-sm text-subtle-2">value: <code>{units}</code></p></div>Composed options
Section titled “Composed options”ToggleButtons.Item children hold any content, such as an icon beside the text. Give an icon-only option an aria-label.
value: grid
Code
<script lang="ts"> import { mdiFormatListBulleted, mdiViewGrid } from "@mdi/js"; import { Icon, ToggleButtons } from "@viamrobotics/prime-ui";
let layout = $state("grid");</script>
<div class="not-content"> <ToggleButtons bind:value={layout} aria-label="Layout"> <ToggleButtons.Item value="grid" class="flex items-center gap-1" aria-label="Grid"> <Icon icon={mdiViewGrid} size="sm" /> Grid </ToggleButtons.Item> <ToggleButtons.Item value="list" class="flex items-center gap-1" aria-label="List"> <Icon icon={mdiFormatListBulleted} size="sm" /> List </ToggleButtons.Item> </ToggleButtons>
<p class="mt-3 text-sm text-subtle-2">value: <code>{layout}</code></p></div>Fully controlled
Section titled “Fully controlled”Pass bind:value a getter and a setter. The setter can decline a change. State & binding explains both modes.
value: free. Enterprise is declined by the setter.
Code
<script lang="ts"> import { ToggleButtons } from "@viamrobotics/prime-ui";
const items = [ { value: "free", label: "Free" }, { value: "team", label: "Team" }, { value: "enterprise", label: "Enterprise" }, ];
let plan = $state("free");</script>
<div class="not-content"> <ToggleButtons {items} aria-label="Plan" bind:value={ () => plan, (next) => { if (next !== "enterprise") plan = next; } } />
<p class="mt-3 text-sm text-subtle-2"> value: <code>{plan}</code>. Enterprise is declined by the setter. </p></div>In a field
Section titled “In a field”Inside a Field, the group takes its id, disabled, state, and the aria-labelledby and aria-describedby from the Label and Hint.
Applies to every measurement on the page.
Code
<script lang="ts"> import { Field, Hint, Label, ToggleButtons } from "@viamrobotics/prime-ui";
const items = [ { value: "mm", label: "mm" }, { value: "cm", label: "cm" }, { value: "in", label: "in" }, ];
let units = $state("mm");</script>
<div class="not-content"> <Field class="flex flex-col gap-1"> <Label>Units</Label> <ToggleButtons bind:value={units} {items} /> <Hint>Applies to every measurement on the page.</Hint> </Field></div>States
Section titled “States”Default
Disabled
One disabled item
Error
Pick the unit the device reports in.
Styling
Section titled “Styling”class on ToggleButtons lands on the group <div>, which is inline-flex. class on ToggleButtons.Item lands on the item button, which wears button. bits-ui sets these data attributes for Tailwind variants.
| Element | Attribute | Value |
|---|---|---|
| group | aria-invalid |
true when state is error |
| group | data-disabled |
present when disabled |
| item | data-state |
on or off |
| item | data-value |
the item’s value |
| item | data-disabled |
present when disabled |
Keyboard
Section titled “Keyboard”Arrow keys move focus only. Selecting is a separate key press.
| Key | Action |
|---|---|
| Tab | Focuses the selected option, or the first. |
| ArrowRight / ArrowDown | Moves focus to the next option, wrapping around. |
| ArrowLeft / ArrowUp | Moves focus to the previous option, wrapping. |
| Home / End | Moves focus to the first or last option. |
| Enter / Space | Selects the focused option. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | string | The selected value. Two-way bindable. | |
items | ToggleButtonsOption[] | Options rendered as items, in order. Omit to compose ToggleButtons.Item children. | |
disabled | boolean | Disable every option. Defaults to the enclosing field's disabled. | |
state | FieldState | Contextual state. Defaults to the enclosing field's state. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'onchange'>, spread onto the element.
ToggleButtons.Item
One option of a ToggleButtons group. Its children are the option’s
content.
Takes extraClasses, children, ...restProps }: Props as its props.