Actions
Button group
Joins related buttons into one pill: actions on the same object, a split button, or a value with a copy button.
import * as ButtonGroup from '@statix/ui/button-group';
import { Button } from '@statix/ui/button';Playground
<ButtonGroup.Root aria-label="Invoice actions">
<Button variant="outline">Download PDF</Button>
<Button variant="outline">Send by email</Button>
<Button variant="outline">Print</Button>
</ButtonGroup.Root>Examples
Basic
Outline buttons share their borders. Only the outer ends stay round.
<script lang="ts">
import * as ButtonGroup from '@statix/ui/button-group';
import { Button } from '@statix/ui/button';
</script>
<ButtonGroup.Root aria-label="Invoice RE-2026-0420">
<Button variant="outline">Download PDF</Button>
<Button variant="outline">Send by email</Button>
<Button variant="outline">Print</Button>
</ButtonGroup.Root>Split button
A main action with a menu next to it. Filled buttons need a ButtonGroup.Separator between them.
<script lang="ts">
import * as ButtonGroup from '@statix/ui/button-group';
import { Button } from '@statix/ui/button';
import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
import RotateCcwIcon from '@lucide/svelte/icons/rotate-ccw';
</script>
<ButtonGroup.Root aria-label="Restore">
<Button variant="dark">
<RotateCcwIcon data-icon="inline-start" />
Restore website
</Button>
<ButtonGroup.Separator class="bg-white/25" />
<Button variant="dark" size="icon" aria-label="Choose a backup">
<ChevronDownIcon />
</Button>
</ButtonGroup.Root>With text
ButtonGroup.Text adds a fixed prefix, here the protocol of an SFTP address.
<script lang="ts">
import * as ButtonGroup from '@statix/ui/button-group';
import { Button } from '@statix/ui/button';
import CopyIcon from '@lucide/svelte/icons/copy';
</script>
<ButtonGroup.Root aria-label="FTP address">
<ButtonGroup.Text>sftp://</ButtonGroup.Text>
<Button variant="outline" class="font-mono text-small">ftp.yoga-berger.de</Button>
<Button variant="outline" size="icon" aria-label="Copy address">
<CopyIcon />
</Button>
</ButtonGroup.Root>Vertical
orientation="vertical" stacks the buttons.
<script lang="ts">
import * as ButtonGroup from '@statix/ui/button-group';
import { Button } from '@statix/ui/button';
</script>
<ButtonGroup.Root orientation="vertical" aria-label="Mailbox info@yoga-berger.de">
<Button variant="outline">Open webmail</Button>
<Button variant="outline">Change password</Button>
<Button variant="outline">Set up a device</Button>
</ButtonGroup.Root>Nested groups
Groups inside a group get an 8px gap between them.
<script lang="ts">
import * as ButtonGroup from '@statix/ui/button-group';
import { Button } from '@statix/ui/button';
import ChevronLeftIcon from '@lucide/svelte/icons/chevron-left';
import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
</script>
<ButtonGroup.Root aria-label="Backups">
<ButtonGroup.Root>
<Button variant="outline" size="icon-sm" aria-label="Previous backup">
<ChevronLeftIcon />
</Button>
<Button variant="outline" size="icon-sm" aria-label="Next backup">
<ChevronRightIcon />
</Button>
</ButtonGroup.Root>
<ButtonGroup.Root>
<Button variant="outline" size="sm">Compare</Button>
<Button variant="outline" size="sm">Download</Button>
</ButtonGroup.Root>
</ButtonGroup.Root>Guidelines
Do
- Group buttons that act on the same thing, such as one invoice.
- Use the same variant and size for every button in a group.
Don't
- Do not put the primary action of a page in a group with secondary ones.
- Do not group more than four buttons. Move the rest into a menu.
Accessibility
- The root has role="group". Give it an aria-label that names the object, for example the invoice number.
- Each button keeps its own focus ring and is raised above its neighbours when focused.
- ButtonGroup.Separator is decorative.
API reference
ButtonGroup.Root
renders<div role="group"> and accepts its attributes| Prop | Type | Default |
|---|---|---|
orientation | 'horizontal' | 'vertical' Joins buttons side by side or stacked. | 'horizontal' |
ref bind | HTMLDivElement | null The group element. | – |
class | ClassValue Merged with the group classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="button-group" | Always present. |
data-orientation | "horizontal" or "vertical". |
ButtonGroup.Text
renders<div> and accepts its attributesA non-interactive pill segment on bg-2 for prefixes and labels.
| Prop | Type | Default |
|---|---|---|
child | Snippet<[{ props }]> Render your own element, for example a <label>, and spread props on it. | – |
ref bind | HTMLDivElement | null The element. | – |
class | ClassValue Merged with the text classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="button-group-text" | Always present. |
ButtonGroup.Separator
renders<div> and accepts its attributesA 1px line between filled buttons.
| Prop | Type | Default |
|---|---|---|
orientation | 'vertical' | 'horizontal' Use horizontal inside a vertical group. | 'vertical' |
class | ClassValue Merged with the separator classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="button-group-separator" | Always present. |
buttonGroupVariants
The tailwind-variants function behind ButtonGroup.Root.