Skip to content
Statix Design System

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

Controls
<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.

sftp://
<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
PropTypeDefault
orientation 'horizontal' | 'vertical'

Joins buttons side by side or stacked.

'horizontal'
ref bindHTMLDivElement | null

The group element.

–
class ClassValue

Merged with the group classes; yours win.

–
Data attributeMeaning
data-slot="button-group"Always present.
data-orientation"horizontal" or "vertical".

ButtonGroup.Text

renders <div> and accepts its attributes

A non-interactive pill segment on bg-2 for prefixes and labels.

PropTypeDefault
child Snippet<[{ props }]>

Render your own element, for example a <label>, and spread props on it.

–
ref bindHTMLDivElement | null

The element.

–
class ClassValue

Merged with the text classes.

–
Data attributeMeaning
data-slot="button-group-text"Always present.

ButtonGroup.Separator

renders <div> and accepts its attributes

A 1px line between filled buttons.

PropTypeDefault
orientation 'vertical' | 'horizontal'

Use horizontal inside a vertical group.

'vertical'
class ClassValue

Merged with the separator classes.

–
Data attributeMeaning
data-slot="button-group-separator"Always present.

buttonGroupVariants

The tailwind-variants function behind ButtonGroup.Root.