Skip to content
Statix Design System

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

Controls
<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
PropTypeDefault
type * 'single' | 'multiple'

One item or many items on at a time.

–
value bindstring | 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 bindHTMLDivElement | null

The group element.

–
class ClassValue

Merged with the group classes.

–
Data attributeMeaning
data-slot="toggle-group"Always present.
data-variant / data-sizeThe current variant and size.
data-spacingThe gap. 0 means the items are joined.
data-orientation"horizontal" or "vertical".

ToggleGroup.Item

renders <button> and accepts its attributes
PropTypeDefault
value * string

The value this item adds.

–
disabled boolean

Disables this item.

false
ref bindHTMLButtonElement | null

The button.

–
class ClassValue

Merged with the item classes; yours win.

–
Data attributeMeaning
data-slot="toggle-group-item"Always present.
data-state"on" or "off".
data-variant / data-size / data-spacingCopied from the root.