Actions
Toggle group
A set of toggles where one or several can be on. Use the chip variant for list filters and outline for a joined view switcher.
import * as ToggleGroup from '@statix/ui/toggle-group';Playground
<ToggleGroup.Root type="single" variant="chip" bind:value aria-label="Filter requests">
<ToggleGroup.Item value="all">All</ToggleGroup.Item>
<ToggleGroup.Item value="open">Open</ToggleGroup.Item>
<ToggleGroup.Item value="waiting">Waiting for customer</ToggleGroup.Item>
<ToggleGroup.Item value="done">Done</ToggleGroup.Item>
</ToggleGroup.Root>Examples
Filter chips
The support queue filter. 36px chips with an 8px gap; the selected chip is ink. Chips get spacing 2 unless you set it.
<script lang="ts">
import * as ToggleGroup from '@statix/ui/toggle-group';
let filter = $state('all');
</script>
<ToggleGroup.Root type="single" variant="chip" bind:value={filter} aria-label="Filter requests">
<ToggleGroup.Item value="all">All</ToggleGroup.Item>
<ToggleGroup.Item value="open">Open</ToggleGroup.Item>
<ToggleGroup.Item value="waiting">Waiting for customer</ToggleGroup.Item>
<ToggleGroup.Item value="done">Done</ToggleGroup.Item>
</ToggleGroup.Root>Several at once
type="multiple" lets the customer combine filters. value is then an array.
<script lang="ts">
import * as ToggleGroup from '@statix/ui/toggle-group';
let types = $state(['wordpress']);
</script>
<ToggleGroup.Root type="multiple" variant="chip" bind:value={types} aria-label="Website type">
<ToggleGroup.Item value="wordpress">WordPress</ToggleGroup.Item>
<ToggleGroup.Item value="shop">Online shop</ToggleGroup.Item>
<ToggleGroup.Item value="static">Static site</ToggleGroup.Item>
</ToggleGroup.Root>Segmented
With spacing 0 (the default outside chips) the items join into one pill. Good for view switchers and periods.
<script lang="ts">
import * as ToggleGroup from '@statix/ui/toggle-group';
import LayoutGridIcon from '@lucide/svelte/icons/layout-grid';
import ListIcon from '@lucide/svelte/icons/list';
</script>
<ToggleGroup.Root type="single" variant="outline" value="grid" aria-label="View">
<ToggleGroup.Item value="grid" aria-label="Grid">
<LayoutGridIcon />
</ToggleGroup.Item>
<ToggleGroup.Item value="list" aria-label="List">
<ListIcon />
</ToggleGroup.Item>
</ToggleGroup.Root>
<ToggleGroup.Root type="single" variant="outline" size="sm" value="30" aria-label="Period">
<ToggleGroup.Item value="7">7 days</ToggleGroup.Item>
<ToggleGroup.Item value="30">30 days</ToggleGroup.Item>
<ToggleGroup.Item value="90">90 days</ToggleGroup.Item>
</ToggleGroup.Root>Toolbar
The default variant suits icon toolbars, for example in a text editor.
<script lang="ts">
import * as ToggleGroup from '@statix/ui/toggle-group';
import BoldIcon from '@lucide/svelte/icons/bold';
import ItalicIcon from '@lucide/svelte/icons/italic';
import LinkIcon from '@lucide/svelte/icons/link';
</script>
<ToggleGroup.Root type="multiple" spacing={1} value={['bold']} aria-label="Text formatting">
<ToggleGroup.Item value="bold" aria-label="Bold">
<BoldIcon />
</ToggleGroup.Item>
<ToggleGroup.Item value="italic" aria-label="Italic">
<ItalicIcon />
</ToggleGroup.Item>
<ToggleGroup.Item value="link" aria-label="Link">
<LinkIcon />
</ToggleGroup.Item>
</ToggleGroup.Root>Guidelines
Do
- Start a filter row with "All" so the customer can reset it in one click.
- Keep chip labels short and use the same words as the status badges in the list.
Don't
- Do not use a toggle group to switch page content. Use Tabs.
- Do not put more than five or six chips in a row. Use a Select for longer lists.
Accessibility
- The root is a group; give it an aria-label such as "Filter requests".
- With type="single" the items behave as radio buttons (role="radio", aria-checked). With type="multiple" they are toggle buttons with aria-pressed.
- Arrow keys move focus between items, Space and Enter toggle the focused one.
- Icon-only items need an aria-label.
API reference
ToggleGroup.Root
renders<div role="group"> and accepts its attributes| Prop | Type | Default |
|---|---|---|
type * | 'single' | 'multiple' One item or many items on at a time. | – |
value bind | string | string[] The selected value (single) or values (multiple). | – |
onValueChange | (value: string | string[]) => void Called when the selection changes. | – |
variant | 'default' | 'outline' | 'chip' Passed to every item. | 'default' |
size | 'sm' | 'md' | 'lg' Passed to every item. default is an alias of md. | 'md' |
spacing | number Gap in Tailwind spacing units. 0 joins items into one pill. | 2 for chip, else 0 |
orientation | 'horizontal' | 'vertical' Layout and arrow-key direction. | 'horizontal' |
disabled | boolean Disables every item. | false |
loop | boolean Arrow keys wrap around. | true |
ref bind | HTMLDivElement | null The group element. | – |
class | ClassValue Merged with the group classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="toggle-group" | Always present. |
data-variant / data-size | The current variant and size. |
data-spacing | The gap. 0 means the items are joined. |
data-orientation | "horizontal" or "vertical". |
ToggleGroup.Item
renders<button> and accepts its attributes| Prop | Type | Default |
|---|---|---|
value * | string The value this item adds. | – |
disabled | boolean Disables this item. | false |
ref bind | HTMLButtonElement | null The button. | – |
class | ClassValue Merged with the item classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="toggle-group-item" | Always present. |
data-state | "on" or "off". |
data-variant / data-size / data-spacing | Copied from the root. |