Skip to main content

ButtonGroup

Join related buttons into one visual control set.

Props
Slots

Anatomy#

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 inside the group for independently pressed actions. ButtonGroup does not coordinate selection or add toolbar keyboard navigation.

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.

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

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

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.

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.

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.

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.

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.

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
data-orientation
Slot: button-group-separator
Description: Stores the rendered orientation (horizontal or vertical).

Props#

ButtonGroup#

Props for the ButtonGroup component. Renders a <div> element by default.

Prop

Separator#

Props for the ButtonGroup.Separator component. Renders a <div> element by default.

Prop