Button Group

ButtonGroup brings adjacent actions into one visual unit. It is useful when multiple controls belong to the same task cluster and should feel coordinated rather than scattered across a toolbar or card footer.

Installation

Purchase access, then open /account/install to issue a registry token.

Usage

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

<ButtonGroup>
  <Button variant="outline">Back</Button>
  <Button variant="outline">Preview</Button>
  <Button>Publish</Button>
</ButtonGroup>

Why This Primitive Exists

Action clusters show up in toolbars, detail panels, and publishing surfaces. ButtonGroup gives those moments a shared wrapper so adjacent button borders and alignment stay intentional.

• Use it when buttons belong to one decision or workflow cluster.
• Prefer it to manual flex spacing when controls should read as one unit.
• Avoid it when actions have very different importance or belong to different tasks.

Examples

Horizontal Group

This is the default orientation and works well for compact toolbars or footer actions.

<ButtonGroup>
  <Button variant="outline">Back</Button>
  <Button>Publish</Button>
</ButtonGroup>

Toolbar Composition

Grouped controls work well when several lower-emphasis actions support a single larger outcome nearby.

<ButtonGroup>
  <Button variant="outline">Filter</Button>
  <Button variant="outline">Export</Button>
  <Button variant="outline">Configure</Button>
</ButtonGroup>

Vertical Stacks

Use the vertical orientation for side rails or dense admin panels where width is constrained.

<ButtonGroup orientation="vertical" className="min-w-52">
  <Button variant="outline">Overview</Button>
  <Button variant="outline">Inventory</Button>
  <Button variant="outline">Publishing</Button>
</ButtonGroup>

In Context

Button groups are most convincing when they hold the closely related secondary actions around one larger outcome.

<div className="flex flex-wrap items-center gap-3">
  <ButtonGroup>
    <Button variant="outline">Save Draft</Button>
    <Button variant="outline">Preview</Button>
    <Button variant="outline">Request Review</Button>
  </ButtonGroup>
  <Button>Publish</Button>
</div>

Guidance

Group Related Decisions Only

• Buttons in the same group should support the same task.
• Keep one group per decision cluster rather than one giant bar of unrelated actions.
• If one action is destructive while the others are routine, separate it visually.

Let Hierarchy Come From The Buttons

• ButtonGroup solves alignment, not priority.
• Use button variants to communicate which action matters most.
• Keep the number of grouped actions small enough to scan quickly.

Choose Orientation By Layout

• Use horizontal groups in headers, footers, and wide toolbars.
• Use vertical groups in side rails and constrained settings panels.
• Add width classes when vertical buttons should align to the same measure.

API Reference

ButtonGroup

ButtonGroup renders a div with role="group" and expects child buttons that expose data-slot="button".

Exports

ButtonGroup also accepts the full React.ComponentProps<"div"> API.