Prepared Docs

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
`alignItems`	`AlignItems`	—	Controls cross-axis alignment of flex children. Maps to CSS `align-items`.
`attachBottom`	`boolean`	—	Removes bottom border-radius, making the box flush against the bottom edge.
`attachLeft`	`boolean`	—	Removes left border-radius, making the box flush against the left edge.
`attachRight`	`boolean`	—	Removes right border-radius, making the box flush against the right edge.
`attachTop`	`boolean`	—	Removes top border-radius, making the box flush against the top edge.
`background`	`Background`	—	Applies a semantic background color token to the box.
`basis`	`string`	—	Sets the initial main size of the flex item. Maps to CSS `flex-basis`.
`border`	`Border`	—	Applies a border style to all sides of the box.
`borderBottom`	`Border`	—	Applies a border style to only the bottom side.
`borderLeft`	`Border`	—	Applies a border style to only the left side.
`borderRadius`	`BorderRadius`	—	Sets the border radius using a design token.
`borderRight`	`Border`	—	Applies a border style to only the right side.
`borderTop`	`Border`	—	Applies a border style to only the top side.
`className`	`string`	—	Additional CSS class name(s) to apply to the box element.
`containerType`	`ContainerType`	—	Enables CSS container queries by setting the `container-type` property.
`display`	`Display.InlineFlex \| Display.Flex`	—	—
`elevation`	`Elevation`	—	Applies a box-shadow elevation level for depth/layering.
`flexWrap`	`FlexWrap`	—	Controls whether flex items wrap onto multiple lines. Maps to CSS `flex-wrap`.
`gap`	`Gap`	—	Spacing between child elements. Maps to CSS `gap`.
`grow`	`boolean`	—	When true, sets `flex-grow: 1` so the element expands to fill available space.
`justifyContent`	`JustifyContent`	—	Controls main-axis alignment of flex children. Maps to CSS `justify-content`.
`margin`	`Spacing`	—	Outer spacing around the box. Accepts a spacing token.
`onClick`	`MouseEventHandler<HTMLDivElement>`	—	Click handler forwarded to the underlying element (along with other DOM props in `...props`).
`onKeyDown`	`KeyboardEventHandler<HTMLDivElement>`	—	Keydown handler forwarded to the underlying element. Useful for div-based controls that need to respond to Enter/Space like a button.
`onPointerDown`	`PointerEventHandler<HTMLDivElement>`	—	Pointer down handler forwarded to the underlying element.
`orientation`	`ButtonGroupOrientation`	`ButtonGroupOrientation.Horizontal`	The orientation of the button group
`overflow`	`Overflow`	—	Controls overflow behavior for content that exceeds the box dimensions.
`padding`	`Spacing`	—	Inner spacing within the box. Accepts a spacing token.
`position`	`Position`	—	Sets the CSS `position` property for layout positioning.
`ref`	`Ref<HTMLDivElement>`	—	Optional ref for the container element
`shrink`	`boolean`	—	When true, sets `flex-shrink: 1` so the element can shrink below its initial size.
`style`	`CSSProperties`	—	Inline styles applied directly to the box element.
`whiteSpace`	`WhiteSpace`	—	Controls the CSS `white-space` property for text wrapping behavior.
`zIndex`	`ZIndex`	—	Sets the CSS `z-index` stacking order using a design token.

Storybook

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

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

ButtonGroup

Name	Type	Default	Description
`alignItems`	`AlignItems`	—	Controls cross-axis alignment of flex children. Maps to CSS `align-items`.
`attachBottom`	`boolean`	—	Removes bottom border-radius, making the box flush against the bottom edge.
`attachLeft`	`boolean`	—	Removes left border-radius, making the box flush against the left edge.
`attachRight`	`boolean`	—	Removes right border-radius, making the box flush against the right edge.
`attachTop`	`boolean`	—	Removes top border-radius, making the box flush against the top edge.
`background`	`Background`	—	Applies a semantic background color token to the box.
`basis`	`string`	—	Sets the initial main size of the flex item. Maps to CSS `flex-basis`.
`border`	`Border`	—	Applies a border style to all sides of the box.
`borderBottom`	`Border`	—	Applies a border style to only the bottom side.
`borderLeft`	`Border`	—	Applies a border style to only the left side.
`borderRadius`	`BorderRadius`	—	Sets the border radius using a design token.
`borderRight`	`Border`	—	Applies a border style to only the right side.
`borderTop`	`Border`	—	Applies a border style to only the top side.
`className`	`string`	—	Additional CSS class name(s) to apply to the box element.
`containerType`	`ContainerType`	—	Enables CSS container queries by setting the `container-type` property.
`display`	`Display.InlineFlex \| Display.Flex`	—	—
`elevation`	`Elevation`	—	Applies a box-shadow elevation level for depth/layering.
`flexWrap`	`FlexWrap`	—	Controls whether flex items wrap onto multiple lines. Maps to CSS `flex-wrap`.
`gap`	`Gap`	—	Spacing between child elements. Maps to CSS `gap`.
`grow`	`boolean`	—	When true, sets `flex-grow: 1` so the element expands to fill available space.
`justifyContent`	`JustifyContent`	—	Controls main-axis alignment of flex children. Maps to CSS `justify-content`.
`margin`	`Spacing`	—	Outer spacing around the box. Accepts a spacing token.
`onClick`	`MouseEventHandler<HTMLDivElement>`	—	Click handler forwarded to the underlying element (along with other DOM props in `...props`).
`onKeyDown`	`KeyboardEventHandler<HTMLDivElement>`	—	Keydown handler forwarded to the underlying element. Useful for div-based controls that need to respond to Enter/Space like a button.
`onPointerDown`	`PointerEventHandler<HTMLDivElement>`	—	Pointer down handler forwarded to the underlying element.
`orientation`	`ButtonGroupOrientation`	`ButtonGroupOrientation.Horizontal`	The orientation of the button group
`overflow`	`Overflow`	—	Controls overflow behavior for content that exceeds the box dimensions.
`padding`	`Spacing`	—	Inner spacing within the box. Accepts a spacing token.
`position`	`Position`	—	Sets the CSS `position` property for layout positioning.
`ref`	`Ref<HTMLDivElement>`	—	Optional ref for the container element
`shrink`	`boolean`	—	When true, sets `flex-shrink: 1` so the element can shrink below its initial size.
`style`	`CSSProperties`	—	Inline styles applied directly to the box element.
`whiteSpace`	`WhiteSpace`	—	Controls the CSS `white-space` property for text wrapping behavior.
`zIndex`	`ZIndex`	—	Sets the CSS `z-index` stacking order using a design token.