---
title: ButtonGroup
description: Join related buttons into one visual control set.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# ButtonGroup

> Join related buttons into one visual control set.

## Anatomy

```text
ButtonGroup [component; slot=root]
├── ButtonGroup.Separator [part; slot=separator]
└── children [internal]
```

The group owns its separators; the caller supplies the child Buttons and their content.

## Usage

Use ButtonGroup when adjacent actions should read as one control set. Each child remains its own
interactive control; the group supplies layout and shared presentation. Use
[ToggleButton](https://moraine.subf.dev/components/toggle-button.md) inside the group for independently pressed actions.
ButtonGroup does not coordinate selection or add toolbar keyboard navigation.

```tsx
import { Button, ButtonGroup } from 'moraine'

export function Example() {
  return (
    <ButtonGroup>
      <Button>Copy</Button>
      <Button variant="outline">Share</Button>
    </ButtonGroup>
  )
}
```

### Composition

Root `size` (`sm`, `md`, `lg`; default `md`), `variant` (default `solid`), and `tone` (default
`primary`) set defaults for every descendant Button. A Button can override any of them. `orientation`
(`horizontal` by default, or `vertical`) sets the layout direction. Compose a menu or popover trigger
as a child when an action needs an overlay.

The root renders a `div` with `role="group"`, so give it an `aria-label`. Set `role="toolbar"` only
if you also provide the toolbar keyboard behavior.

```tsx
<ButtonGroup variant="outline" size="sm" aria-label="Document actions">
  <Button>Copy link</Button>
  <Button>Duplicate</Button>
  <Button>Archive</Button>
</ButtonGroup>
```

### Separator

Insert `ButtonGroup.Separator` only where an explicit boundary is useful. Its orientation is
perpendicular to the group axis: vertical in a horizontal group and horizontal in a vertical group.
It renders a `div` with `role="separator"`.

```tsx
<ButtonGroup aria-label="Clipboard actions">
  <Button>Copy</Button>
  <ButtonGroup.Separator />
  <Button>Paste</Button>
</ButtonGroup>
```

## Examples

### Group document actions

Join copy, duplicate, and archive so they read as one set of file commands.

```tsx
import { Button, ButtonGroup } from 'moraine'

export function GroupComposition() {
  return (
    <div class="flex flex-col gap-4 items-start">
      <ButtonGroup>
        <Button variant="outline">Copy link</Button>
        <Button variant="outline">Duplicate</Button>
        <Button variant="outline">Archive</Button>
      </ButtonGroup>
    </div>
  )
}
```

### Format selected text

Compose ToggleButton children for independently pressed actions. They inherit the group's `size`,
`tone`, and `variant` (the unpressed appearance); `activeVariant` controls each button's pressed
appearance.

```tsx
import { ButtonGroup, ToggleButton } from 'moraine'

export function ToggleButtons() {
  return (
    <ButtonGroup size="sm" aria-label="Text formatting">
      <ToggleButton leading="i-lucide:bold" defaultPressed>
        Bold
      </ToggleButton>
      <ToggleButton leading="i-lucide:italic">Italic</ToggleButton>
      <ToggleButton leading="i-lucide:underline">Underline</ToggleButton>
    </ButtonGroup>
  )
}
```

### Split clipboard actions

Use a separator to distinguish copy from paste without changing either button's semantics.

```tsx
import { Button, ButtonGroup } from 'moraine'

export function SeparatorExample() {
  return (
    <ButtonGroup variant="soft" tone="neutral" aria-label="Clipboard actions">
      <Button>Copy</Button>
      <ButtonGroup.Separator />
      <Button>Paste</Button>
    </ButtonGroup>
  )
}
```

### Export a report with format options

Keep the primary export command on a Button and attach extra formats through a dropdown trigger.

```tsx
import { Button, ButtonGroup, DropdownMenu, Icon } from 'moraine'
import type { DropdownMenuT } from 'moraine'
import { createSignal } from 'solid-js'

export function DropdownAction() {
  const [exportedFormat, setExportedFormat] = createSignal<string>()

  const exportItems: DropdownMenuT.Item[] = [
    {
      type: 'group',
      label: 'Export report',
      items: [
        {
          label: 'PDF document',
          description: 'Best for sharing and printing',
          icon: 'i-lucide:file-text',
          onSelect: () => setExportedFormat('PDF'),
        },
        {
          label: 'CSV spreadsheet',
          description: 'Best for analysis and imports',
          icon: 'i-lucide:table-2',
          onSelect: () => setExportedFormat('CSV'),
        },
        {
          label: 'JSON data',
          description: 'Best for integrations',
          icon: 'i-lucide:braces',
          onSelect: () => setExportedFormat('JSON'),
        },
      ],
    },
  ]

  return (
    <div class="flex flex-col gap-3 items-start">
      <ButtonGroup>
        <Button leading="i-lucide:download">Export report</Button>
        <ButtonGroup.Separator />
        <DropdownMenu placement="bottom" align="end">
          <DropdownMenu.Trigger as={Button} size="icon-md">
            <Icon name="i-lucide:chevron-down" />
          </DropdownMenu.Trigger>
          <DropdownMenu.Content items={exportItems} />
        </DropdownMenu>
      </ButtonGroup>

      <p class="text-sm text-muted-foreground min-h-5" role="status" aria-live="polite">
        {exportedFormat() ? `Report exported as ${exportedFormat()}.` : 'Choose an export format.'}
      </p>
    </div>
  )
}
```

### Save a document with extra options

Attach a popover trigger when the extra action opens a short panel rather than a menu of commands.

```tsx
import { Button, ButtonGroup, Icon, Popover } from 'moraine'

export function ButtonPopover() {
  return (
    <ButtonGroup aria-label="Document actions">
      <Button leading="i-lucide:save">Save document</Button>
      <Popover>
        <Popover.Trigger as={Button} size="icon-md" aria-label="Open save options">
          <Icon name="i-lucide:chevron-down" />
        </Popover.Trigger>
        <Popover.Content>
          <div class="p-3 space-y-1">
            <p class="text-sm font-medium">Save options</p>
            <p class="text-xs text-muted-foreground">Choose where to save this document.</p>
          </div>
        </Popover.Content>
      </Popover>
    </ButtonGroup>
  )
}
```

### Zoom a canvas from a vertical toolbar

Set `orientation="vertical"` for stacked icon controls such as zoom.

```tsx
import { Button, ButtonGroup } from 'moraine'

export function Vertical() {
  return (
    <ButtonGroup orientation="vertical" variant="outline" aria-label="Zoom">
      <Button size="icon-md" leading="i-lucide:plus" activeEffect="none" aria-label="Zoom in" />
      <Button size="icon-md" leading="i-lucide:minus" activeEffect="none" aria-label="Zoom out" />
    </ButtonGroup>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-orientation` | `button-group-separator` | Stores the rendered orientation (horizontal or vertical). |

### Props

#### ButtonGroup

Props for the ButtonGroup component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| id | string \| undefined | — | `id` attribute of the group root element, for example to reference it from `aria-labelledby`. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'horizontal' | Visual layout direction. |
| role | JSX.AriaAttributes['role'] \| undefined | 'group' | ARIA role of the group root. Use `'toolbar'` only when you also provide the toolbar keyboard<br>behavior yourself; the group adds none. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Shared button size. |
| tone | Tone \| undefined | 'primary' | Shared button tone. |
| variant | 'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link' \| undefined | 'solid' | Shared button treatment. |
| children | JSX.Element \| undefined | — | Buttons rendered as one joined set, optionally with `ButtonGroup.Separator` between them.<br>Descendant `Button`s inherit the group's `size`, `variant` and `tone` unless they set their own. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

#### ButtonGroup.Separator

Props for the ButtonGroup.Separator component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
