ButtonGroup
Import
Section titled “Import”import { ButtonGroup, Button } from '@delightstack/components';Basic Usage
Section titled “Basic Usage”View code
<ButtonGroup aria-label="Document actions"> <Button>Save</Button> <Button>Save as</Button> <Button>Discard</Button></ButtonGroup>Examples
Section titled “Examples”Segmented control
Section titled “Segmented control”Bind value and the group owns the selection: each child Button with a value becomes a toggle (aria-pressed), the selected one fills, the rest stay quiet inside one shared frame. This is the control to reach for with 2–5 mutually exclusive options — every option visible, one click each. When an option has a visual consequence, show it instead of naming it. Add translucent for a quieter control: the selected option becomes a neutral chip instead of the brand fill, for secondary choices (a view switcher in a toolbar) that shouldn’t compete with the page’s primary actions.
Showing the week at weight 400, as a list.
View code
<script> let range = $state('week'); let weight = $state(400); let view = $state('list');</script>
<ButtonGroup bind:value={range} aria-label="Date range"> <Button value="day">Day</Button> <Button value="week">Week</Button> <Button value="month">Month</Button></ButtonGroup>
<ButtonGroup bind:value={weight} aria-label="Font weight"> <Button value={300} tooltip="Light"><span style:font-weight="300">Aa</span></Button> <Button value={400} tooltip="Regular"><span style:font-weight="400">Aa</span></Button> <Button value={700} tooltip="Bold"><span style:font-weight="700">Aa</span></Button></ButtonGroup>
<ButtonGroup bind:value={view} translucent aria-label="View"> <Button value="list">List</Button> <Button value="board">Board</Button> <Button value="calendar">Calendar</Button></ButtonGroup>Toggle Group (Single Selection)
Section titled “Toggle Group (Single Selection)”Use the active prop on child Buttons to create a toggle group.
Icon buttons rarely speak for themselves, so pass a tooltip to each one. Hover a
button and its tooltip appears after a short delay — then slide across to the next
button and its tooltip shows instantly, no waiting. The skip-delay window is
shared by every tooltip on the page and persists briefly after you leave, so the
buttons don’t even need to touch.
View code
<script> import { ButtonGroup, Button } from '@delightstack/components';
let viewMode = $state('grid');</script>
<ButtonGroup size="0" aria-label="View mode"> <Button active={viewMode === 'grid'} onclick={() => viewMode = 'grid'} icon tooltip="Grid view" aria-label="Grid view"> <svg viewBox="0 0 24 24" fill="currentColor"> <path d="M3 3h8v8H3V3zm0 10h8v8H3v-8zm10-10h8v8h-8V3zm0 10h8v8h-8v-8z"/> </svg> </Button> <Button active={viewMode === 'list'} onclick={() => viewMode = 'list'} icon tooltip="List view" aria-label="List view"> <svg viewBox="0 0 24 24" fill="currentColor"> <path d="M3 13h2v-2H3v2zm0 4h2v-2H3v2zm0-8h2V7H3v2zm4 4h14v-2H7v2zm0 4h14v-2H7v2zM7 7v2h14V7H7z"/> </svg> </Button></ButtonGroup>Variant Inheritance
Section titled “Variant Inheritance”Set variant props on the group to apply them to all children at once.
View code
<ButtonGroup outline accent aria-label="Accent group"> <Button>First</Button> <Button>Second</Button> <Button>Third</Button></ButtonGroup>Vertical Orientation
Section titled “Vertical Orientation”Stack buttons vertically instead of horizontally.
View code
<ButtonGroup orientation="vertical" aria-label="Options"> <Button>Option 1</Button> <Button>Option 2</Button> <Button>Option 3</Button></ButtonGroup>Split Button with Dropdown
Section titled “Split Button with Dropdown”Combine a primary action button with a dropdown trigger inside a group.
<script> import { ButtonGroup, Button } from '@delightstack/components';</script>
<ButtonGroup aria-label="Save options"> <Button onclick={primarySave}>Save</Button> <Button icon aria-label="More save options"> <!-- ChevronDownIcon --> {#snippet menu({ close })} <button onclick={() => { saveAs(); close(); }}>Save As...</button> <button onclick={() => { saveCopy(); close(); }}>Save copy</button> {/snippet} </Button></ButtonGroup>Detached (Non-Attached) Mode
Section titled “Detached (Non-Attached) Mode”Set attached={false} to add a small gap between buttons instead of merging borders.
View code
<ButtonGroup attached={false} aria-label="Spaced actions"> <Button>One</Button> <Button>Two</Button> <Button>Three</Button></ButtonGroup>| Prop | Type | Default | Description |
|---|---|---|---|
size | '0000' | '000' | '00' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | undefined | Size applied to all child Buttons via context |
outline | boolean | false | Apply outline variant to all children |
transparent | boolean | false | Apply transparent variant to all children |
translucent | boolean | false | Apply translucent variant to all children. In segmented mode, the selected option becomes a neutral chip instead of the brand fill |
accent | boolean | false | Apply accent color to all children |
error | boolean | false | Apply error color to all children |
success | boolean | false | Apply success color to all children |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Layout direction |
disabled | boolean | false | Disable all child Buttons via context |
attached | boolean | true | Visually connect buttons (shared borders, merged radii). Ignored in segmented mode |
value | string | number | undefined | Bindable selected value. Setting it turns the group into a segmented control |
onchange | (value) => void | undefined | Called when the user picks an option |
id | string | auto-generated | Element ID |
class | string | '' | Additional CSS classes |
children | Snippet | undefined | Child Button components |
The ButtonGroup exports a ButtonGroupContext interface used for its context contract with child Buttons:
interface ButtonGroupContext { size: | undefined | '0000' | '000' | '00' | '0' | '1' | '2' | '3' | '4' | '5' | '6'; outline: boolean; transparent: boolean; translucent: boolean; accent: boolean; error: boolean; success: boolean; disabled: boolean;}Child Buttons read this context via getContext('button-group') and merge the group values with their own props (own props take precedence when explicitly set).
Accessibility
Section titled “Accessibility”role="group"on the container element- Provide an
aria-labelto describe the group’s purpose - Buttons remain individually focusable
- Hovered and focused buttons are raised above siblings via
z-indexfor clean border visibility