---
title: "ToggleGroup"
description: "A row of toggles with single or multiple selection."
category: "Form & Input"
slug: toggle-group
url: /components/toggle-group
since: "0.2.0"
status: "stable"
---

# ToggleGroup

A row of toggles with single or multiple selection.

## Import

```svelte
import { ToggleGroup } from '@elluzion/iv-ui';
```

## Preview

One pressed toggle; choosing another releases the first.

```svelte
<script lang="ts">
	import { ToggleGroup } from '@elluzion/iv-ui';

	let view = $state('list');
</script>

<div class="stack">
	<ToggleGroup label="View" mode="single" items={['list', 'grid', 'table']} bind:value={view} />
	<p class="readout">view: {view}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: start;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

## Usage

- `mode="single"` behaves like a segmented control; `"none"` only emits clicks.
- Items may be strings or `{ value, label, icon, disabled }`.
- Bind `value`; it is a string for single mode and an array for multiple.

## Examples

### Multiple

Several toggles can stay pressed at once.

```svelte
<script lang="ts">
	import { ToggleGroup } from '@elluzion/iv-ui';

	let columns = $state<string[]>(['status', 'owner']);
</script>

<div class="stack">
	<ToggleGroup
		label="Columns"
		mode="multiple"
		items={['status', 'owner', 'updated', 'branch']}
		bind:value={columns}
	/>
	<p class="readout">shown: {columns.join(', ') || '—'}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: start;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Icons

Items with icons keep their labels for wide layouts.

```svelte
<script lang="ts">
	import { IconLayoutGrid, IconList, IconTable } from '@tabler/icons-svelte';
	import { ToggleGroup } from '@elluzion/iv-ui';

	let view = $state('grid');

	const items = [
		{ value: 'list', label: 'List', icon: IconList },
		{ value: 'grid', label: 'Grid', icon: IconLayoutGrid },
		{ value: 'table', label: 'Table', icon: IconTable }
	];
</script>

<ToggleGroup label="View" mode="single" {items} bind:value={view} />
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ToggleGroupItem[]` | `[]` | Toggles to render. Items may be strings or `{ value, label, icon, disabled }`. |
| `mode` | `ToggleGroupMode` | `'none'` | Selection behaviour: one value, many values, or none. |
| `value` **bindable** | `string \| string[]` | `mode === 'multiple' ? [] : ''` | Selected value(s). Bind with `bind:value`. |
| `label` | `string` | `''` | Accessible name for the group. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Stacking direction. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |

All native `<div>` attributes are forwarded.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: string \| string[] }>) => void` | Called with `{ value }` after a selection changes. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |

### Types

#### `ToggleGroupMode`

Selection behaviour of a toggle group.

```ts
type ToggleGroupMode = 'single' | 'multiple' | 'none';
```

#### `ToggleGroupItem`

A toggle description or a plain string label.

```ts
type ToggleGroupItem =
	| string
	| {
			value: string;
			label?: string;
			icon?: Icon;
			disabled?: boolean;
	  };
```

### Tokens used

`--iv_radius` · `--iv_radius-lg` · `--iv_radius-sm` · `--iv_tg-radius`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-checked` · `.iv-disabled` · `.iv-lg` · `.iv-sm` · `.iv-toggle` · `.iv-toggle-group` · `.iv-vertical`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus through the toggles. |
| `Space / Enter` | Toggles the focused item. |

- The container uses `role="group"` and is named by `label`.
- Each option is a button with `aria-pressed`.
- Selection is never changed by arrow keys, so every item stays reachable with Tab.

## Related

- [Toggle](/components/toggle.md)
- [ButtonGroup](/components/button-group.md)
- [Tabs](/components/tabs.md)
- [Button](/components/button.md)