---
title: "ButtonGroup"
description: "Joins related buttons into one segmented control."
category: "Form & Input"
slug: button-group
url: /components/button-group
since: "0.2.0"
status: "stable"
---

# ButtonGroup

Joins related buttons into one segmented control.

## Import

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

## Preview

A segmented control with one active option.

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

	let period = $state('week');
</script>

<div class="stack">
	<ButtonGroup label="Period" mode="single" items={['day', 'week', 'month']} bind:value={period} />
	<p class="readout">period: {period}</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="none"` is a plain toolbar; `single` and `multiple` track selection.
- Items may be strings or `{ value, label, icon, disabled }`.
- `variant` applies to every button; `size` keeps the row consistent.

## Examples

### Multiple

Toggle several options and read the array value.

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

	let filters = $state<string[]>(['errors']);
</script>

<div class="stack">
	<ButtonGroup
		label="Filters"
		mode="multiple"
		items={['errors', 'warnings', 'info']}
		bind:value={filters}
	/>
	<p class="readout">active: {filters.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>
```

### Vertical

`orientation="vertical"` stacks the buttons.

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

	let action = $state('deploy');
</script>

<ButtonGroup
	label="Run"
	mode="single"
	orientation="vertical"
	variant="outline"
	items={['deploy', 'rollback', 'restart']}
	bind:value={action}
/>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ButtonGroupItem[]` | `[]` | Buttons to render. Items may be strings or `{ value, label, icon, disabled }`. |
| `mode` | `ButtonGroupMode` | `'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. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |
| `variant` | `ButtonGroupVariant` | `'secondary'` | Visual emphasis for every button in the group. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Stacking direction. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `fullWidth` | `boolean` | `false` | Stretches the group to the container width. |

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

#### `ButtonGroupMode`

Selection behaviour of a button group.

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

#### `ButtonGroupVariant`

Emphasis applied to every button in the group.

```ts
type ButtonGroupVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
```

#### `ButtonGroupItem`

A button description or a plain string label.

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

### Tokens used

`--iv_cursor` · `--iv_radius-sm` · `--iv_reverse-bg` · `--iv_reverse-fg` · `--iv_reverse-hover` · `--iv_surface`

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

### CSS hooks

`.iv-btn` · `.iv-btn-group` · `.iv-disabled` · `.iv-full-width` · `.iv-selected` · `.iv-vertical`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus through the group. |
| `Space / Enter` | Activates the focused button. |

- The container uses `role="group"` and is named by `label`.
- Selectable options expose `aria-pressed`; toolbar mode leaves it off.
- `disabled` disables every button in the group.

## Related

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