Skip to content

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 value for the whole group, bindable. Options come from items, or from ToggleButtons.Item children.
  • One option is always selected: clicking the selected option does not clear it.
  • Takes state, disabled, and its labelling from an enclosing Field, or directly. error sets aria-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 a role="group", and the selected one carries data-state="on".

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>

bind:value on the group. The items need no binding of their own.

value: mm

Code
TwoWay.svelte
<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>

ToggleButtons.Item children hold any content, such as an icon beside the text. Give an icon-only option an aria-label.

value: grid

Code
Composed.svelte
<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>

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
Controlled.svelte
<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>

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
InField.svelte
<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>

Default

Disabled

One disabled item

Error

Pick the unit the device reports in.

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

Arrow keys move focus only. Selecting is a separate key press.

KeyAction
TabFocuses the selected option, or the first.
ArrowRight / ArrowDownMoves focus to the next option, wrapping around.
ArrowLeft / ArrowUpMoves focus to the previous option, wrapping.
Home / EndMoves focus to the first or last option.
Enter / SpaceSelects the focused option.
PropTypeDefaultDescription
bind:valuestringThe selected value. Two-way bindable.
itemsToggleButtonsOption[]Options rendered as items, in order. Omit to compose ToggleButtons.Item children.
disabledbooleanDisable every option. Defaults to the enclosing field's disabled.
stateFieldStateContextual 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.