Button Group

A container that groups related buttons together with consistent styling.

<ButtonGroup>
  <Button variant="outline">Button 1</Button>
  <Button variant="outline">Button 2</Button>
</ButtonGroup>

Installation

pnpm dlx cubix@latest add button-group --base aria

Usage

Import

import { Button } from "@/components/cubix/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/cubix/button-group"

Example

<ButtonGroup>
  <Button variant="outline">Button 1</Button>
  <Button variant="outline">Button 2</Button>
</ButtonGroup>

Composition

Use the following composition to build a ButtonGroup:

ButtonGroup
├── Button or Input
├── ButtonGroupSeparator
└── ButtonGroupText

Accessibility

The group has role="group".
Use Tab to move between the controls in the group.
Label the group with aria-label or aria-labelledby.
Icon-only buttons inside the group need their own aria-label.

Examples

Orientation

Set the orientation prop to change the layout.

<ButtonGroup orientation="vertical" aria-label="Media controls">
  <Button variant="outline" size="icon" aria-label="Increase">
    <PlusIcon />
  </Button>
  <Button variant="outline" size="icon" aria-label="Decrease">
    <MinusIcon />
  </Button>
</ButtonGroup>

Size

Control size with the size prop on each button.

<ButtonGroup>
  <Button variant="outline" size="sm">Small</Button>
  <Button variant="outline" size="sm">Button</Button>
</ButtonGroup>
<ButtonGroup>
  <Button variant="outline">Default</Button>
  <Button variant="outline">Button</Button>
</ButtonGroup>
<ButtonGroup>
  <Button variant="outline" size="lg">Large</Button>
  <Button variant="outline" size="lg">Button</Button>
</ButtonGroup>

Nested

Nest ButtonGroup components to create groups with spacing.

<ButtonGroup>
  <ButtonGroup>
    <Button variant="outline" size="icon" aria-label="Add">
      <PlusIcon />
    </Button>
  </ButtonGroup>
  <ButtonGroup>
    <Button variant="outline">Archive</Button>
    <Button variant="outline">Report</Button>
  </ButtonGroup>
</ButtonGroup>

Separator

Outline buttons already have a border. For other variants, add ButtonGroupSeparator to split the group.

<ButtonGroup>
  <Button variant="secondary">Button 1</Button>
  <ButtonGroupSeparator />
  <Button variant="secondary">Button 2</Button>
</ButtonGroup>

Split

Pair a main action with a DropdownMenu trigger for a split button.

<ButtonGroup>
  <Button variant="outline">Update</Button>
  <DropdownMenu>
    <DropdownMenuTrigger render={<Button variant="outline" size="icon" aria-label="More options" />}>
      <ChevronDownIcon />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end">
      <DropdownMenuItem>Disable</DropdownMenuItem>
      <DropdownMenuItem variant="destructive">Uninstall</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</ButtonGroup>

Input

Wrap an input with buttons in the same group.

<ButtonGroup>
  <Input placeholder="Type something here..." />
  <Button variant="outline">Search</Button>
</ButtonGroup>

Text

Use ButtonGroupText for a prefix or label inside the group.

https://

<ButtonGroup>
  <ButtonGroupText>https://</ButtonGroupText>
  <Input placeholder="example.com" />
</ButtonGroup>

Select

Pair the group with a Select and an input.

<ButtonGroup>
  <Select defaultValue="$">
    <SelectTrigger aria-label="Currency">
      <SelectValue />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="$">$</SelectItem>
      <SelectItem value="€">€</SelectItem>
      <SelectItem value="£">£</SelectItem>
    </SelectContent>
  </Select>
  <Input placeholder="Enter amount to send" />
  <Button variant="outline" size="icon" aria-label="Send">
    <ArrowRightIcon />
  </Button>
</ButtonGroup>

RTL

Joined corners and borders use logical start/end, so the group stays correct under dir="rtl". To enable RTL support, see the Direction guide.

<div dir="rtl" lang="fa" className="flex flex-wrap justify-center gap-2">
  <ButtonGroup>
    <Button variant="outline">ادامه</Button>
    <Button variant="outline">انصراف</Button>
  </ButtonGroup>
  <ButtonGroup>
    <Button variant="outline">
      ادامه
      <ArrowLeftIcon data-icon="inline-end" />
    </Button>
    <Button variant="outline" size="icon" aria-label="افزودن">
      <PlusIcon />
    </Button>
  </ButtonGroup>
</div>

API Reference

Note: Use ButtonGroup for related actions. Use a toggle group when the controls represent a selected state.

ButtonGroup

The container that groups related buttons with consistent styling.

Prop	Type	Default	Description
orientation	"horizontal" \| "vertical"	"horizontal"	Layout direction of the grouped controls.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Buttons, inputs, separators, text, or nested ButtonGroups.

ButtonGroupSeparator

A visual divider between buttons in the group.

Prop	Type	Default	Description
orientation	"horizontal" \| "vertical"	"vertical"	Divider direction. Vertical is the usual split between side-by-side buttons.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

ButtonGroupText

Text shown inside the group, such as a prefix or label.

Prop	Type	Default	Description
render	React.ReactElement	-	Base UI / React Aria: render the text slot as another element, such as a label.
asChild	boolean	false	Radix: merge props onto the child element instead of a wrapping div.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Label or helper text shown inside the group.