ButtonGroup
Joins related buttons into one segmented control.
import { ButtonGroup } from '@elluzion/iv-ui'; 01 Preview
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>02 Usage
mode="none"is a plain toolbar;singleandmultipletrack selection.- Items may be strings or
{ value, label, icon, disabled }. variantapplies to every button;sizekeeps the row consistent.
03 Examples
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}
/>04 API
import { ButtonGroup } from '@elluzion/iv-ui';Props
10 props · 1 events · 1 snippets| 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 |
|---|---|---|
| onchange | (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.
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;
};05 Accessibility
| Keys | Action |
|---|---|
| Tab | Moves focus through the group. |
| Space / Enter | Activates the focused button. |
- The container uses
role="group"and is named bylabel. - Selectable options expose
aria-pressed; toolbar mode leaves it off. disableddisables every button in the group.
06 Tokens & CSS hooks
Tokens used
Class hooks
.iv-btn.iv-btn-group.iv-disabled.iv-full-width.iv-selected.iv-vertical