Skip to content
iv-ui v0.3.0

ButtonGroup

since 0.2.0

Joins related buttons into one segmented control.

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

Single

A segmented control with one active option.

period: week

Source· svelte Show Hide
<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>
  • 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.

Multiple

Toggle several options and read the array value.

active: errors

Source· svelte Show Hide
<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.

Source· svelte Show Hide
<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}
/>
import { ButtonGroup } from '@elluzion/iv-ui';

Props

10 props · 1 events · 1 snippets
PropTypeDefaultDescription
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 bindablestring | 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 booleanfalseDisables interaction and applies the disabled treatment.
fullWidth booleanfalseStretches the group to the container width.

All native <div> attributes are forwarded.

Events

EventHandler typeDescription
onchange(e: CustomEvent<{ value: string | string[] }>) => voidCalled with { value } after a selection changes.

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

Snippets

SnippetTypeDescription
childrenSnippetContent rendered inside the component.

Types

ButtonGroupMode

Selection behaviour of a button group.

type ButtonGroupMode = 'single' | 'multiple' | 'none';
ButtonGroupVariant

Emphasis applied to every button in the group.

type ButtonGroupVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
ButtonGroupItem

A button description or a plain string label.

type ButtonGroupItem =
	| string
	| {
			value: string;
			label?: string;
			icon?: Icon;
			disabled?: boolean;
	  };
KeysAction
TabMoves focus through the group.
Space / EnterActivates 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.
Class hooks
.iv-btn.iv-btn-group.iv-disabled.iv-full-width.iv-selected.iv-vertical
iv-ui
↑ ↓ navigate ↵ open esc close minisearch · 482 records