# ButtonGroup

> Joins a row of adjacent actions into one seamless control — one border, one divider, no doubled edges.

- Package: `fancy-ui-svelte` (Svelte 5 + Tailwind CSS v4)
- Category: Actions
- Tags: button, group, segmented, split button, toolbar, actions
- Docs: https://fancy-ui.rama.app/docs/components/button-group
- Source: https://github.com/RamaHerbin/fancy-ui/tree/main/src/lib/fancy-ui/button-group

## Import

```svelte
<script lang="ts">
  import { ButtonGroup } from 'fancy-ui-svelte';
</script>
```

Setup (once per project): `npm install fancy-ui-svelte`, then add `@import "fancy-ui-svelte/tailwind.css";` after `@import "tailwindcss";` in your main CSS file. Full guide: https://fancy-ui.rama.app/llms.txt

React: `import { ButtonGroup } from 'fancy-ui-react';` (same prop names; `class` becomes `className`, snippets become `ReactNode`).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Stacking axis for the joined items |
| `label` | `string` | — | Accessible name for the group, exposed as aria-label |
| `class` | `string` | — | Additional CSS classes |
| `ref` | `HTMLDivElement \| null` | `null` | Bindable reference to the root <div> |

## Snippets

| Snippet | Description |
| --- | --- |
| `children` | The adjacent actions to join |

## Examples

### Basic Usage

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { ButtonGroup } from "fancy-ui-svelte";
</script>

<ButtonGroup label="Clipboard actions">
	<Button variant="outline">Cut</Button>
	<Button variant="outline">Copy</Button>
	<Button variant="outline">Paste</Button>
</ButtonGroup>
```

### Segmented Control

A Day / Week / Month picker; the active item is the demo's own state, not ButtonGroup's.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { ButtonGroup } from "fancy-ui-svelte";

	const ranges = ["Day", "Week", "Month"];
	let active = $state("Day");
</script>

<ButtonGroup label="Time range">
	{#each ranges as range (range)}
		<Button variant={range === active ? "secondary" : "ghost"} onclick={() => (active = range)}>
			{range}
		</Button>
	{/each}
</ButtonGroup>
```

### Split Button

A wide primary action and a narrow trailing trigger, joined by the same seam.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { ButtonGroup } from "fancy-ui-svelte";
</script>

<ButtonGroup label="Save document">
	<Button variant="secondary">Save</Button>
	<Button variant="secondary" class="px-[10px]" label="More save options">▼</Button>
</ButtonGroup>
```

### Vertical

orientation="vertical" stacks the items and rotates the divider onto the same axis.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { ButtonGroup } from "fancy-ui-svelte";
</script>

<ButtonGroup orientation="vertical" label="Panel position">
	<Button variant="outline">Top</Button>
	<Button variant="outline">Middle</Button>
	<Button variant="outline">Bottom</Button>
</ButtonGroup>
```