Skip to content
WunderUI

Button Group

Free

Join a few related buttons into one control with shared borders, in a row or a stack.

npx wunderui-cli add button-group

Playground

Installation

bash
npx wunderui-cli add button-group

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Segment for exactly one choice out of a few options
  • Radio Button Group for one choice with radio semantics and a form value
  • Toggle for options that stay on or off
  • Button for a single action, or actions that do not belong together

Orientation

A row is the default. Stack the buttons in a narrow panel, where only the top and bottom ends keep their corners.

Shape

Rounded is the default. Use the pill when the group sits next to other fully rounded controls.

Content

Buttons hold a label, an icon and a label, or an icon only. Use the same kind throughout a group, and give icon-only buttons an aria-label.

Sizes

The group takes any Button size. Give every button the same one, because the shared borders only line up at the same height.

Size

States

Each button has its own hover, pressed and disabled state. The focused button moves on top, so its ring stays visible.

Split button

A Split Button has two parts: the main action and a chevron that opens a menu. Press the chevron to see it.

Keyboard interactions

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

TaborShiftTab
Moves focus to the next or previous button in the group, in the order they are written. A disabled button is skipped.
EnterorSpace
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 and motion

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

The buttons are the parts, and the group only draws the row. The Split Button is a ready-made group of two.

  • data-slot="button-group"

    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.

  • 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.

  • Optional

    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.

  • data-slot="split-button"Optional

    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.

  • data-slot="split-button-action"
  • data-slot="split-button-menu"

Best practices

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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

    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

Button Group is a div with the group role and takes its native attributes. Split Button wraps a Button, so it also takes the Button props.

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.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal" puts the buttons in a row, stacks them with shared edges.
shape"rounded" | "pill""rounded" gives the two outer ends the Button corner radius, makes them fully rounded.

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.

PropTypeDefaultDescription
variant"plain" | "solid""plain" is a white button with a border, has the primary fill.
size"lg" | "xl" | "sm" | "md" | "2xl""md"The same sizes as the Button: is 32 px, 36, 40, 44 and 48. The menu part is as wide as the button is high.
shape"rounded" | "pill""rounded" or , as on the Button Group.
menuReactNode—The entries of the menu: , and the other Dropdown Menu parts.
onActionMouseEventHandler<HTMLButtonElement>—Runs when the action part is pressed. The menu part opens the menu and does not call it.
iconReactNode—A leading icon of the action part. It is decorative.
menuLabelstring"More actions"The accessible name of the menu part, since it shows only a chevron. The default is .
disabledboolean—Disables both parts.
childrenReactNode—The label of the action part.
defaultOpenboolean—Whether the menu is open at the start, when you do not control it.
focusableWhenDisabledbooleanfalseKeeps a disabled action part in the tab order.
groupClassNamestring—Extra classes for the group that wraps both parts.
menuPropsSplitButtonMenuProps—Props for the menu popup, for example . The default is .
nativeButtonbooleantrueWhether the action part renders a native .
onOpenChange(open) => void—Called with the new open state whenever the menu opens or closes.
openboolean—The controlled open state of the menu.
pendingboolean—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: , or , as on the Button.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("button-group")
Installnpx wunderui-cli add button-group

The full library index for assistants is at /llms.txt.