Skip to main content
Give a group an accessible name and place related buttons inside it. The group joins adjacent borders and can apply defaults for size, variant, and color. Buttons retain their own tab stops.

Usage

State ownership

ButtonGroup coordinates appearance, not selection. It has no controlled or uncontrolled selection mode. Each button receives its own action handler and application state; see Button’s state ownership example for loading behavior. For a mutually exclusive choice, use RadioGroup, which owns selection for its radio controls.

Appearance precedence

Each appearance prop resolves independently: the child’s explicit prop, then the group default, then the component default. This applies to both Button and IconButton, including an explicit IconButton size="xs". Defaults reach children through fragments, wrappers, and tooltip anchors. Keep attached buttons at the same size so their edges align. This example overrides variant and color while inheriting the group size.

Detached controls

Set attached={false} to keep each control’s rounded corners and a 2px gap. Group defaults still apply through wrappers and tooltip anchors; explicit child props take precedence.

Framed controls

Set framed to add a translucent background, border, 2px padding, and concentric corners. The frame works with attached or detached controls and preserves explicit child appearance. Use size="xs" on IconButton for compact 20px actions.

Updating existing groups

Replace IconButtonGroup and its iconButtons array with ButtonGroup framed attached={false} and explicit children. Replace InsideButton with LightIconButton size="xs". Each button owns its accessible name, action handler, disabled state, and optional tooltip.

Props

boolean
default:"true"
Join adjacent controls. Set to false for independently rounded buttons with a 2px gap.
"accent" | "danger" | "neutral" | "success"
Default semantic color for children without an explicit color.
boolean
default:"false"
Add a translucent frame with padding and concentric corners. Button sizes and appearance remain independent unless set on the group.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
"md" | "sm"
Default button height for children without an explicit size.
"ghost" | "link" | "outline" | "soft" | "solid"
Default surface treatment for children without an explicit variant.