# Button Group

Groups related buttons into a single visual unit.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="button-group" />

<ComponentPreview name="button-group" title="button-group.tsx">
<ButtonGroupDemo />
</ComponentPreview>

Groups adjacent buttons into a single visual unit. Buttons inside a group share borders and outer corners so they read as one control. Works with `Button`, `Input`, `Select`, `DropdownMenu`, and anything that renders `[data-slot]`.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add button-group
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Install registry dependencies.
</Step>

Button Group imports `Slot` and `Separator`. Install both first.

<ComponentSource name="slot" title="components/ui/slot.tsx" />

<ComponentSource name="separator" title="components/ui/separator.tsx" />

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="button-group" title="components/ui/button-group.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="button-group.tsx"
import { Button } from "@/components/ui/button";
import { ButtonGroup } from "@/components/ui/button-group";
```

```tsx title="button-group.tsx"
<ButtonGroup>
  <Button variant="outline">Archive</Button>
  <Button variant="outline">Report</Button>
  <Button variant="outline">Snooze</Button>
</ButtonGroup>
```

## Orientation [#orientation]

<ComponentPreview name="button-group-orientation" title="button-group-orientation.tsx" src="examples/button-group-orientation.tsx">
<k />
</ComponentPreview>

Pass `orientation="vertical"`. Borders and radii adjust so the group reads as one column.

## Size [#size]

<ComponentPreview name="button-group-size" title="button-group-size.tsx" src="examples/button-group-size.tsx">
<g />
</ComponentPreview>

Buttons inside a group keep their own `size`. The group does not enforce a size, so you can mix and match.

## Split [#split]

<ComponentPreview name="button-group-split" title="button-group-split.tsx" src="examples/button-group-split.tsx">
<x />
</ComponentPreview>

`ButtonGroupSeparator` adds a thin divider between adjacent buttons. Use it when the visual separation between actions matters more than the tight border merge.

## Separator [#separator]

<ComponentPreview name="button-group-separator" title="button-group-separator.tsx" src="examples/button-group-separator.tsx">
<u />
</ComponentPreview>

## Dropdown [#dropdown]

<ComponentPreview name="button-group-dropdown" title="button-group-dropdown.tsx" src="examples/button-group-dropdown.tsx">
<ButtonGroupDropdown />
</ComponentPreview>

`DropdownMenuTrigger` with `as={Button}` inside a `ButtonGroup` renders as a button that visually joins the group.

## Input [#input]

<ComponentPreview name="button-group-input" title="button-group-input.tsx" src="examples/button-group-input.tsx">
<f />
</ComponentPreview>

## Input Group [#input-group]

<ComponentPreview name="button-group-input-group" title="button-group-input-group.tsx" src="examples/button-group-input-group.tsx">
<ButtonGroupInputGroup />
</ComponentPreview>

## Nested [#nested]

<ComponentPreview name="button-group-nested" title="button-group-nested.tsx" src="examples/button-group-nested.tsx">
<A />
</ComponentPreview>

`ButtonGroup` can be nested. Inner groups opt out of the outer group border merging via the `data-slot` attribute.

## Select [#select]

<ComponentPreview name="button-group-select" title="button-group-select.tsx" src="examples/button-group-select.tsx">
<ButtonGroupSelect />
</ComponentPreview>

`SelectTrigger` inside a group widens with `w-fit` unless you set a width, so the trigger never pushes adjacent buttons off the group.

## API Reference [#api-reference]

### ButtonGroup [#buttongroup]

<PropsTable rows={[{"name":"orientation","type":"horizontal | vertical","default":"horizontal","description":"Direction of the group."},{"name":"className","type":"string","description":"Additional CSS classes merged with cn()."},{"name":"props","type":"React.ComponentProps<div>","description":"Forwarded to the root div."}]} />

### ButtonGroupText [#buttongrouptext]

<PropsTable rows={[{"name":"as","type":"React.ElementType","description":"Renders a different root element or component. Defaults to div."},{"name":"className","type":"string","description":"Additional CSS classes."}]} />

### ButtonGroupSeparator [#buttongroupseparator]

Wraps `Separator` with group-aware styling. Accepts every `Separator` prop. See [Separator](/docs/components/separator) for the base API.

## Accessibility [#accessibility]

- `ButtonGroup` sets `role="group"` and `data-orientation` on the root div, so screen readers announce the grouped context.
- Children keep their own roles and labels. The group does not override them.
- Icon-only buttons inside the group still need an `aria-label` on the button itself, not on the group.

## Best Practices [#best-practices]

- **Group actions that belong to the same task.** Archive and Report belong together. Archive and Delete do not.
- **Keep group size uniform.** Mixing `sm` and `lg` inside a group reads as a bug, not a feature.
- **Use `ButtonGroupSeparator` sparingly.** The default border merge is enough for most cases.
- **Nested groups need an outer ButtonGroup.** The outer wrapper adds the gap and keeps the composition readable.

## Custom radius [#custom-radius]

Override `--radius` on the wrapper to square off or fully round the group. All children inherit the variable.

```tsx
<ButtonGroup className="[--radius:9999rem]">
  <Button variant="outline">Back</Button>
  <Button variant="outline">Next</Button>
</ButtonGroup>
```

## Related Components [#related-components]

- [Button](/docs/components/button): the base button used inside groups
- [Separator](/docs/components/separator): the divider used between buttons
- [Slot](/docs/components/slot): the primitive behind `as`
- [Theming](/docs/guides/theming): customize colors and borders