elementsbutton-group

ButtonGroup

Cohesive group of related buttons with shared size, variant, and orientation.

Import#

import { Button, ButtonGroup } from 'moraine'

Usage#

ButtonGroup joins the edges of direct button children and provides shared size and variant defaults. A child Button can override either default when needed.

Add an accessible label when the surrounding content does not already name the group.

Set separator to render a decorative separator between adjacent controls. Customize its root with the separator slot in classes or styles.

<ButtonGroup separator classes={{ separator: 'text-primary' }}>
  <Button>Export</Button>
  <Button>Share</Button>
</ButtonGroup>

Slot Structure#

root
├── Button (x n)
└── separator (between adjacent children, optional)

Examples#

Basic#

1
function Basic() {
2
  return (
3
    <ButtonGroup variant="outline" aria-label="Document history">
4
      <Button leading="i-lucide:undo-2">Undo</Button>
5
      <Button leading="i-lucide:redo-2">Redo</Button>
6
    </ButtonGroup>
7
  )
8
}

Variants#

1
function Variants() {
2
  const VARIANTS: ButtonGroupVariant[] = ['default', 'secondary', 'outline', 'ghost', 'destructive']
3

4
  return (
5
    <div class="flex flex-wrap gap-3">
6
      <For each={VARIANTS}>
7
        {(variant) => (
8
          <ButtonGroup variant={variant} aria-label={`${variant} actions`}>
9
            <Button>Previous</Button>
10
            <Button>Next</Button>
11
          </ButtonGroup>
12
        )}
13
      </For>
14
    </div>
15
  )
16
}

Sizes#

1
function Sizes() {
2
  const SIZES: ButtonGroupSize[] = ['xs', 'sm', 'md', 'lg', 'xl']
3

4
  return (
5
    <div class="flex flex-wrap gap-3 items-end">
6
      <For each={SIZES}>
7
        {(size) => (
8
          <ButtonGroup size={size} variant="outline" aria-label={`${size} pagination`}>
9
            <Button>1</Button>
10
            <Button>2</Button>
11
            <Button>3</Button>
12
          </ButtonGroup>
13
        )}
14
      </For>
15
    </div>
16
  )
17
}

Orientations#

Horizontal and vertical groups using compact quantity controls.

1
function Vertical() {
2
  return (
3
    <div class="flex flex-wrap gap-6 items-start">
4
      <ButtonGroup variant="outline" aria-label="Horizontal quantity controls">
5
        <Button size="icon-md" leading="i-lucide:minus" aria-label="Decrease quantity" />
6
        <Button size="icon-md" leading="i-lucide:plus" aria-label="Increase quantity" />
7
      </ButtonGroup>
8

9
      <ButtonGroup orientation="vertical" variant="outline" aria-label="Vertical quantity controls">
10
        <Button size="icon-md" leading="i-lucide:plus" aria-label="Increase quantity" />
11
        <Button size="icon-md" leading="i-lucide:minus" aria-label="Decrease quantity" />
12
      </ButtonGroup>
13
    </div>
14
  )
15
}

Separators#

Toggle separators between adjacent controls with a switch.

1
function Separator() {
2
  const [showSeparator, setShowSeparator] = createSignal(true)
3

4
  return (
5
    <div class="flex flex-col gap-4 items-start">
6
      <Switch label="Show separators" checked={showSeparator()} onChange={setShowSeparator} />
7

8
      <ButtonGroup separator={showSeparator()} aria-label="Document actions">
9
        <Button leading="i-lucide:download">Export</Button>
10
        <Button leading="i-lucide:share-2">Share</Button>
11
        <Button leading="i-lucide:archive">Archive</Button>
12
      </ButtonGroup>
13
    </div>
14
  )
15
}

Compose a primary button with a Popover trigger inside the same group.

1
function ButtonPopover() {
2
  return (
3
    <ButtonGroup separator aria-label="Document actions">
4
      <Button leading="i-lucide:save">Save document</Button>
5
      <Popover
6
        content={
7
          <div class="space-y-1">
8
            <p class="text-sm font-medium">Save options</p>
9
            <p class="text-xs text-muted-foreground">Choose where to save this document.</p>
10
          </div>
11
        }
12
      >
13
        <Button size="icon-md" aria-label="Open save options">
14
          <Icon name="i-lucide:chevron-down" />
15
        </Button>
16
      </Popover>
17
    </ButtonGroup>
18
  )
19
}

A report export action composed from a button trigger and a dropdown menu.

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

4
  const exportItems: DropdownMenuT.Item[] = [
5
    {
6
      type: 'group',
7
      label: 'Export report',
8
      children: [
9
        {
10
          label: 'PDF document',
11
          description: 'Best for sharing and printing',
12
          icon: 'i-lucide:file-text',
13
          onSelect: () => setExportedFormat('PDF'),
14
        },
15
        {
16
          label: 'CSV spreadsheet',
17
          description: 'Best for analysis and imports',
18
          icon: 'i-lucide:table-2',
19
          onSelect: () => setExportedFormat('CSV'),
20
        },
21
        {
22
          label: 'JSON data',
23
          description: 'Best for integrations',
24
          icon: 'i-lucide:braces',
25
          onSelect: () => setExportedFormat('JSON'),
26
        },
27
      ],
28
    },
29
  ]
30

31
  return (
32
    <div class="flex flex-col gap-3 items-start">
33
      <ButtonGroup separator>
34
        <Button leading="i-lucide:download">Export report</Button>
35
        <DropdownMenu items={exportItems}>
36
          <Button size="icon-md">
37
            <Icon name="i-lucide:chevron-down" />
38
          </Button>
39
        </DropdownMenu>
40
      </ButtonGroup>
41

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

API Reference#

Attributes#

Slotroot4 attributes

Container that joins the edges of its direct button children.

Data Attributes

Data Attribute	Description
data-orientation	Stores the rendered orientation.
data-size	Stores the resolved size variant.
data-variant	Stores the resolved visual variant.

ARIA Attributes

ARIA Attribute	Description
role	Defines the semantic role exposed to assistive technology.

Props#

Prop	Type	Default	Description
children	`JSX.Element`	—	Buttons or compatible controls rendered as a cohesive group.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`ButtonGroupT.Classes \| undefined`	—	—
id	`string \| undefined`	—	Optional identifier for the group root.
orientation	`"horizontal" \| "vertical" \| undefined`	—	—
ref	`JSX.HTMLElementTags["div"] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
role	`JSX.AriaAttributes["role"] \| undefined`	—	ARIA role for the group root.
separator	`boolean \| undefined`	—	Whether to render a decorative separator between adjacent controls.
size	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "icon-xs" \| "icon-sm" \| "icon-md" \| "icon-lg" \| "icon-xl" \| undefined`	—	—
style	`JSX.CSSProperties \| undefined`	—	—
styles	`ButtonGroupT.Styles \| undefined`	—	—
variant	`"link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| undefined`	—	—