# Button Group

A row of connected buttons sharing borders and outer corners, for view switchers or segmented actions.

- Category: Core Elements
- Page: https://wunderui.com/components/button-group
- Tier: Free

## Install

```bash
npx wunderui-cli add button-group
```

## Import

```tsx
import { ButtonGroup, ButtonGroupOrientation, ButtonGroupShape, SplitButton } from "@/components/ui/button-group"
```

## Minimal usage

Then use it:

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

export function ShareOptions() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain">Share</Button>
      <Button variant="plain">Export</Button>
      <Button variant="plain">Print</Button>
    </ButtonGroup>
  )
}
```

Expected result: You see three plain buttons joined into one control, with one border between each pair and rounded corners only at the outer ends.

## Usage

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

export function Example() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain">Share</Button>
      <Button variant="plain">Export</Button>
      <Button variant="plain">Print</Button>
    </ButtonGroup>
  )
}
```

## When to use

### Use Button Group for

- A few related actions that belong together, such as zoom, share and export, or previous and next
- Icon buttons that act on the same thing, such as the four paging controls of a list
- A main action with a few alternatives behind a menu, with the Split Button

### Use something else

- [Segment](https://wunderui.com/components/segment) for exactly one choice out of a few options
- [Radio Button Group](https://wunderui.com/components/radio-button-group) for one choice with radio semantics and a form value
- [Toggle](https://wunderui.com/components/toggle) for options that stay on or off
- [Button](https://wunderui.com/components/button) for a single action, or actions that do not belong together

## Keyboard

Button Group is a plain container, so the browser handles focus and activation for its buttons.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous button in the group, in the order they are written. A disabled button is skipped. |
| `Enter` or `Space` | Presses the focused button. On the chevron of a Split Button it opens the menu. |

The group is not a toolbar, so arrow keys do not move focus between its buttons (use a Toolbar for that). A Split Button menu follows the Dropdown Menu keys.

## Behavior

What the group does with its buttons, the DOM and motion.

- **Joined edges:** Only the first and last buttons keep rounded corners, left and right in a row, top and bottom in a stack. Each button overlaps its neighbour's border by 1 px.
- **Shape:** Shape is rounded, matching the Button corner radius, or pill, with fully rounded ends. In a stack the pill ends stay corners, not half circles.
- **Focus:** The focused button rises above its neighbours, so its indigo border and 2 px ring stay fully visible.
- **Split button:** The action part runs the action handler and the menu part opens a Dropdown Menu. The menu part is as wide as the button is high and stays pressed while its menu is open.
- **Names:** The group has no name by default. Add an aria-label to it, and to every icon-only button.
- **Motion:** The group itself does not move: each button changes its fill quickly and scales to 0.97 while pressed. A Split Button menu animates like a Dropdown Menu.
- **Reduced motion:** With reduced motion the press scale and spinner rotation are off, and the fills still change.

## Anatomy

- `ButtonGroup`: A row, or a stack when vertical, that joins its children so only the two outer ends keep their corners. Shape is rounded or pill, and you name the group with an aria-label.
- `Button`: Each direct child, usually a plain Button or Icon Button of the same size. The group sets the corners and overlaps borders, and the focused button moves on top so its ring shows.
- `Shared edge`: One border between two neighbours: the next button overlaps the border of the previous one by 1 px, so two buttons never draw a double line.
- `SplitButton`: Two parts: the action with its label and optional icon, and a chevron that opens a Dropdown Menu. Each has its own hover, pressed and open fill; keyboard focus shows through the fill, with no ring.
- `Split Button Action`
- `Split Button Menu`

## Best practices

### When to use

- Use a Button Group for a few related actions that belong together, such as share, export and print, or zoom in and zoom out. For one choice that stays selected, use a Segment or a Radio Button Group.

### Do

- Give the group an aria-label that names what the buttons do together, such as Zoom. It is already a group, but has no name.
- Use the same variant and size on every button, and plain buttons in most cases. Shared borders only line up when the buttons have the same height and border.
- Name every icon-only button in a group with an aria-label, and keep to one kind of content: all text, all icons, or all icon and text.
- Use a Split Button when one action is far more common than its alternatives, and put the alternatives in its menu.

### Don't

- Don't wrap the buttons in extra elements. Only direct children get the joined corners, so a wrapper breaks the edges.
- Don't put a primary or gradient button in the group. Joined buttons read as equals, and a view has one main action.
- Don't use a group to pick an option. Joined buttons look like a choice but have no selected state, so use a Segment.

## API reference

### ButtonGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| orientation | "horizontal" \| "vertical" | "horizontal" | `horizontal` puts the buttons in a row, `vertical` stacks them with shared edges. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` gives the two outer ends the Button corner radius, `pill` makes them fully rounded. |

Also accepts React.HTMLAttributes attributes.

### SplitButton

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  | The label of the action part. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the action part, merged with its own. |
| defaultOpen | boolean |  | Whether the menu is open at the start, when you do not control it. |
| disabled | boolean |  | Disables both parts. |
| focusableWhenDisabled | boolean | false | Keeps a disabled action part in the tab order. |
| groupClassName | string |  | Extra classes for the group that wraps both parts. |
| icon | React.ReactNode |  | A leading icon of the action part. It is decorative. |
| menu | React.ReactNode |  | The entries of the menu: `DropdownMenuItem`, `DropdownMenuSeparator` and the other Dropdown Menu parts. |
| menuLabel | string | "More actions" | The accessible name of the menu part, since it shows only a chevron. The default is `More actions`. |
| menuProps | SplitButtonMenuProps |  | Props for the menu popup, for example `align`. The default is `align="end"`. |
| nativeButton | boolean | true | Whether the action part renders a native `<button>`. |
| onAction | React.MouseEventHandler<HTMLButtonElement> |  | Runs when the action part is pressed. The menu part opens the menu and does not call it. |
| onOpenChange | (open: boolean) => void |  | Called with the new open state whenever the menu opens or closes. |
| open | boolean |  | The controlled open state of the menu. |
| pending | boolean |  | Shows a spinner in place of the leading icon of the action part and ignores presses. |
| phase | "error" \| "success" \| "pending" \| "idle" |  | Async feedback on the action part: `pending`, `success` or `error`, as on the Button. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the action part. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` or `pill`, as on the Button Group. |
| size | "lg" \| "xl" \| "sm" \| "md" \| "2xl" | "md" | The same sizes as the Button: `sm` is 32 px, `md` 36, `lg` 40, `xl` 44 and `2xl` 48. The menu part is as wide as the button is high. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the action part, or a function that returns them from its state. |
| variant | "plain" \| "solid" | "plain" | `plain` is a white button with a border, `solid` has the primary fill. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Orientation: a row or a stack

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

export function Example() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain">Share</Button>
      <Button variant="plain">Export</Button>
      <Button variant="plain">Print</Button>
    </ButtonGroup>
  )
}
```

### Shape: rounded or pill

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

export function Example() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain">Share</Button>
      <Button variant="plain">Export</Button>
      <Button variant="plain">Print</Button>
    </ButtonGroup>
  )
}
```

### Content: text, icon and text, or icon only

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

export function Example() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain">Share</Button>
      <Button variant="plain">Export</Button>
      <Button variant="plain">Print</Button>
    </ButtonGroup>
  )
}
```

### Size: 36, 40 and 44 px

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

export function Example() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain" size="md">Share</Button>
      <Button variant="plain" size="md">Export</Button>
      <Button variant="plain" size="md">Print</Button>
    </ButtonGroup>
  )
}
```

### States: default, hover, focus and a disabled item

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

export function Example() {
  return (
    <ButtonGroup aria-label="Share options">
      <Button variant="plain">Share</Button>
      <Button variant="plain">Export</Button>
      <Button variant="plain">Print</Button>
    </ButtonGroup>
  )
}
```

### Split button: a main action and a menu

```tsx
import { SplitButton } from "@/components/ui/button-group"
import { exportMenu } from "./export-menu"

export function Example() {
  // exportMenu is a list of DropdownMenuItem entries, imported from "@/components/ui/dropdown-menu".
  return (
    <SplitButton menu={exportMenu}>
      Export
    </SplitButton>
  )
}
```

### Segmented selector

One choice out of a few, such as an order type. A radio group styled as a button group, with the chosen option in the indigo tint.

```tsx
<ButtonGroup role="radiogroup" aria-label="Order type">
  {options.map((option) => (
    <Button
      key={option}
      variant="plain"
      role="radio"
      aria-checked={value === option}
      onClick={() => setValue(option)}
      className={value === option ? "bg-tint-indigo text-tint-text-indigo hover:bg-tint-indigo" : undefined}
    >
      {option}
    </Button>
  ))}
</ButtonGroup>
```

### Selector with tier badges

Each option carries a badge with its plan tier, so the choice and its cost read together.

```tsx
<ButtonGroup role="radiogroup" aria-label="Model">
  <Button variant="plain" role="radio" aria-checked>
    Standard
    <Badge color="indigo" badgeStyle="light" shape="pill">Pro</Badge>
  </Button>
  …
</ButtonGroup>
```

### Vertical group

A vertical group stacks the buttons with shared edges. Only the top and bottom corners are rounded.

```tsx
<ButtonGroup orientation="vertical" aria-label="Account sections">
  <Button variant="plain" className="justify-start"><User />Profile</Button>
  <Button variant="plain" className="justify-start"><CreditCard />Billing</Button>
  <Button variant="plain" className="justify-start"><Users />Team</Button>
</ButtonGroup>
```

### Menu with a status indicator

The trigger shows the current choice with its status dot. The menu lists the same dots, and the chosen row is checked.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="plain" />}>
    <span aria-hidden className="size-2 rounded-full bg-success" />
    Online
    <ChevronDown data-icon="inline-end" />
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuRadioGroup value={status} onValueChange={setStatus}>
      <DropdownMenuRadioItem value="online">…</DropdownMenuRadioItem>
    </DropdownMenuRadioGroup>
  </DropdownMenuContent>
</DropdownMenu>
```

### Buttons with a badge

A count cell sits between two buttons and shares their edges. It is a badge, not a button, so it takes no focus.

```tsx
<ButtonGroup>
  <Button variant="plain"><MessageSquare />Comments</Button>
  <Badge color="grey" badgeStyle="light_border" className="h-(--control-md) px-3 text-sm tabular-nums">24</Badge>
  <Button variant="plain"><Share2 />Share</Button>
</ButtonGroup>
```

### Button with a menu

A split button: the main action on the left, the other ways to do it behind the chevron on the right.

```tsx
<ButtonGroup>
  <Button>Publish</Button>
  <DropdownMenu>
    <DropdownMenuTrigger render={<IconButton aria-label="More publish options" className="border-l-white/30" />}>
      <ChevronDown />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end">…</DropdownMenuContent>
  </DropdownMenu>
</ButtonGroup>
```

## In context

### Zoom controls: icon buttons around a readout

Zoom out and zoom in are disabled at the limits. The readout in the middle resets the zoom to 100 %.

```tsx
import { useState } from "react"
import { Minus, Plus } from "lucide-react"
import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { IconButton } from "@/components/ui/icon-button"

const MIN = 50
const MAX = 200

export function Example() {
  const [zoom, setZoom] = useState(100)

  return (
    <div className="flex items-center justify-between gap-4 rounded-xl border border-border bg-card p-4">
      <span className="text-sm font-medium">Atlas redesign.png</span>
      <ButtonGroup aria-label="Zoom">
        <IconButton variant="plain" aria-label="Zoom out" disabled={zoom <= MIN} onClick={() => setZoom(zoom - 25)}>
          <Minus />
        </IconButton>
        <Button variant="plain" className="w-16 tabular-nums" aria-label={`Zoom ${zoom} percent, reset to 100 percent`} onClick={() => setZoom(100)}>
          {zoom}%
        </Button>
        <IconButton variant="plain" aria-label="Zoom in" disabled={zoom >= MAX} onClick={() => setZoom(zoom + 25)}>
          <Plus />
        </IconButton>
      </ButtonGroup>
    </div>
  )
}
```

### Export: a split button in a card header

The main action runs the common export. The menu holds the other formats, and the card says what is running.

```tsx
import { useState } from "react"
import { SplitButton } from "@/components/ui/button-group"
import { ExportMenuItems } from "./export-menu-items"

export function Example() {
  const [status, setStatus] = useState("Choose a format or press Export.")

  // ExportMenuItems renders DropdownMenuItem entries, imported from "@/components/ui/dropdown-menu".
  return (
    <div className="flex items-center justify-between gap-4 rounded-xl border border-border bg-card p-4">
      <div className="flex flex-col">
        <span className="text-sm font-medium">Invoices</span>
        <span className="text-sm text-text-secondary">{status}</span>
      </div>
      <SplitButton onAction={() => setStatus("Exporting 12 invoices as PDF…")} menu={<ExportMenuItems onSelect={(format) => setStatus(`Exporting 12 invoices as ${format}…`)} />}>
        Export
      </SplitButton>
    </div>
  )
}
```

### Pagination: four icon buttons in one group

First, previous, next and last page. Buttons that cannot move are disabled at the ends of the list.

```tsx
import { useState } from "react"
import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from "lucide-react"
import { ButtonGroup } from "@/components/ui/button-group"
import { IconButton } from "@/components/ui/icon-button"

const PAGES = 12

export function Example() {
  const [page, setPage] = useState(3)

  return (
    <div className="flex items-center justify-between gap-4">
      <span className="text-sm text-text-secondary">
        Page {page} of {PAGES}
      </span>
      <ButtonGroup aria-label="Pagination">
        <IconButton variant="plain" aria-label="First page" disabled={page === 1} onClick={() => setPage(1)}>
          <ChevronsLeft />
        </IconButton>
        <IconButton variant="plain" aria-label="Previous page" disabled={page === 1} onClick={() => setPage(page - 1)}>
          <ChevronLeft />
        </IconButton>
        <IconButton variant="plain" aria-label="Next page" disabled={page === PAGES} onClick={() => setPage(page + 1)}>
          <ChevronRight />
        </IconButton>
        <IconButton variant="plain" aria-label="Last page" disabled={page === PAGES} onClick={() => setPage(PAGES)}>
          <ChevronsRight />
        </IconButton>
      </ButtonGroup>
    </div>
  )
}
```

## For AI agents

`get_component("button-group")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
