Button group

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

ButtonGroup is a flex container (role="group") that visually merges adjacent Button elements on the shared grouped-control tray (inset-subtle fill, alt2 border — same chrome as SegmentedControl / ToggleGroup). ButtonGroupSeparator inserts space between nested groups; ButtonGroupText adds a labeled static segment on that tray. Orientation is ButtonGroupOrientation.Horizontal (default) or Vertical.

ButtonGroup

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-labelledby`	`string`	—	Id of the element that names this group; use {@link ButtonGroupLabelledByProps} instead. Id of the element that names this group.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	{@link Button } segments, plus {@link ButtonGroupText }, {@link ButtonGroupSeparator }, and nested {@link ButtonGroup } clusters. The group does not restyle anchors or other elements into buttons.
`defaultValue`	`DisplayValue \| null`	—	The Default variant has no group selection; use {@link ButtonGroupVariant.Expanding}. Value of the selected {@link ButtonGroupItem } on first render when uncontrolled. Defaults to none.
`label`	`LocalizedMessage`	—	Accessible name for the group (`role="group"`). Accessible name prop; use {@link ButtonGroupLabelProps} instead.
`onValueChange`	`((value: DisplayValue, details: ChangeDetails<ChangeReason>) => void)`	—	The Default variant has no group selection; use {@link ButtonGroupVariant.Expanding}. Called when a segment is pressed. `details.reason` is {@link ChangeReason.ItemPress }. Pressing the selected segment does not call it: a selection cannot be cleared by the person using the group. Cancel the change to keep the previous selection. @param value - The pressed segment's value @param details - Change metadata
`orientation`	`ButtonGroupOrientation`	—	Main-axis layout. Defaults to {@link ButtonGroupOrientation.Horizontal}. The Expanding variant is a row; a column is not defined. Defaults to {@link ButtonGroupOrientation.Horizontal}.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the group element.
`size`	`ButtonSize`	—	Size passed to every direct {@link Button } child, and to nested groups, that sets no `size` of its own. A segment's own `size` wins. Defaults to {@link ButtonSize.Large}.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`value`	`DisplayValue \| null`	—	The Default variant has no group selection; use {@link ButtonGroupVariant.Expanding}. Value of the selected {@link ButtonGroupItem } when controlled; `null` selects none.
`variant`	`ButtonGroupVariant`	—	Look of the group. Defaults to {@link ButtonGroupVariant.Default}. Makes the selected segment grow to show its label while the others stay icon-only. Hovering a collapsed segment with a mouse or pen, or moving keyboard focus to it, shows its label in a Tooltip and never changes a width; touch shows no tooltip, a tap selects. Pressing a segment selects it and shows its label.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Name	Type	Default	Description
`ButtonGroupSeparator`	`Box props + orientation`	`—`	Gap between sub-groups.
`ButtonGroupText`	`FlexBox props`	`—`	Non-action label segment.

Basic

With icon button

Nested groups

Vertical orientation

With text

With separator

Small buttons

All variants

Single button

Icon buttons only

With status dot

Lead and tail icons

Button Group / Usage

Button Group / Accessibility

On this page

Button group

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

ButtonGroup

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-labelledby`	`string`	—	Id of the element that names this group; use {@link ButtonGroupLabelledByProps} instead. Id of the element that names this group.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	{@link Button } segments, plus {@link ButtonGroupText }, {@link ButtonGroupSeparator }, and nested {@link ButtonGroup } clusters. The group does not restyle anchors or other elements into buttons.
`defaultValue`	`DisplayValue \| null`	—	The Default variant has no group selection; use {@link ButtonGroupVariant.Expanding}. Value of the selected {@link ButtonGroupItem } on first render when uncontrolled. Defaults to none.
`label`	`LocalizedMessage`	—	Accessible name for the group (`role="group"`). Accessible name prop; use {@link ButtonGroupLabelProps} instead.
`onValueChange`	`((value: DisplayValue, details: ChangeDetails<ChangeReason>) => void)`	—	The Default variant has no group selection; use {@link ButtonGroupVariant.Expanding}. Called when a segment is pressed. `details.reason` is {@link ChangeReason.ItemPress }. Pressing the selected segment does not call it: a selection cannot be cleared by the person using the group. Cancel the change to keep the previous selection. @param value - The pressed segment's value @param details - Change metadata
`orientation`	`ButtonGroupOrientation`	—	Main-axis layout. Defaults to {@link ButtonGroupOrientation.Horizontal}. The Expanding variant is a row; a column is not defined. Defaults to {@link ButtonGroupOrientation.Horizontal}.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the group element.
`size`	`ButtonSize`	—	Size passed to every direct {@link Button } child, and to nested groups, that sets no `size` of its own. A segment's own `size` wins. Defaults to {@link ButtonSize.Large}.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`value`	`DisplayValue \| null`	—	The Default variant has no group selection; use {@link ButtonGroupVariant.Expanding}. Value of the selected {@link ButtonGroupItem } when controlled; `null` selects none.
`variant`	`ButtonGroupVariant`	—	Look of the group. Defaults to {@link ButtonGroupVariant.Default}. Makes the selected segment grow to show its label while the others stay icon-only. Hovering a collapsed segment with a mouse or pen, or moving keyboard focus to it, shows its label in a Tooltip and never changes a width; touch shows no tooltip, a tap selects. Pressing a segment selects it and shows its label.