ButtonContainer Component

The ButtonContainer component groups related buttons together with consistent spacing, layout, and connected visual styling. Adjacent buttons have their shared corners flattened for a cohesive appearance.

Usage

Basic Horizontal Group

By default, buttons are arranged horizontally with connected corners.

<ButtonContainer aria-label="Form actions">
  <Button label="Cancel" type="outlined" />
  <Button label="Save" status="success" />
</ButtonContainer>

Vertical Layout

Use the direction prop to stack buttons vertically.

<ButtonContainer direction="vertical" aria-label="Options">
  <Button label="Option 1" type="outlined" />
  <Button label="Option 2" type="outlined" />
  <Button label="Option 3" type="outlined" />
</ButtonContainer>

Multiple Buttons

ButtonContainer works with any number of buttons, flattening corners between adjacent buttons while preserving outer corners.

<ButtonContainer aria-label="Pagination">
  <Button label="First" type="outlined" />
  <Button label="Previous" type="outlined" />
  <Button label="1" type="solid" />
  <Button label="2" type="outlined" />
  <Button label="3" type="outlined" />
  <Button label="Next" type="outlined" />
  <Button label="Last" type="outlined" />
</ButtonContainer>

RTL Support

Use flipForTextDirection to automatically reverse button order in right-to-left contexts.

<ButtonContainer flipForTextDirection aria-label="Confirmation">
  <Button label="Cancel" type="outlined" />
  <Button label="Confirm" status="success" />
</ButtonContainer>

Custom Element

Use the as prop to render as a semantic HTML element like nav, menu, or fieldset.

<ButtonContainer as="nav" aria-label="Navigation actions">
  <Button label="Back" type="outlined" />
  <Button label="Next" status="primary" />
</ButtonContainer>

Different Button Types

ButtonContainer works with all button type variants.

<ButtonContainer aria-label="Solid buttons">
  <Button label="One" type="solid" />
  <Button label="Two" type="solid" />
</ButtonContainer>

<ButtonContainer aria-label="Outlined buttons">
  <Button label="One" type="outlined" />
  <Button label="Two" type="outlined" />
</ButtonContainer>

Inside Container

ButtonContainer works correctly when nested inside Container components, automatically respecting the depth-based border radius system.

<Container status="primary">
  <ButtonContainer aria-label="Container actions">
    <Button label="Cancel" type="outlined" />
    <Button label="Save" />
  </ButtonContainer>
</Container>

Props

Name	Type	Default	Description
`children`	`JSX.Element`	required	Button elements to render inside the container
`direction`	`"horizontal" \| "vertical"`	"horizontal"	Layout direction of buttons
`flipForTextDirection`	`boolean`	false	Reverse button order based on text direction (e.g., RTL flips order)
`as`	`string`	"div"	HTML element to render as (e.g., "nav", "fieldset", "menu")
`aria-label`	`string`	required	Accessible label describing the button group
`styles`	`StyleXStyles`	undefined	Additional StyleX styles to apply to the container

Connected Corner Styling

ButtonContainer automatically flattens the corners where adjacent buttons meet, creating a seamless visual connection:

horizontal - Left button has rounded left corners, right button has rounded right corners, shared corners are flat

vertical - Top button has rounded top corners, bottom button has rounded bottom corners, shared corners are flat

This styling uses CSS selectors and !important to override the depth-based radius calculations from the Container system, ensuring consistent appearance regardless of nesting depth.

Theming

ButtonContainer uses the following theme token for customization:

buttonContainerGap - Gap between buttons (defaults to spaceXS)

Override this token in your theme to adjust the spacing between grouped buttons.

Accessibility

The ButtonContainer component includes accessibility features:

Renders with role="group" to indicate related controls

Requires aria-label prop to describe the button group purpose

Supports semantic HTML elements via the as prop (nav, menu, fieldset)

RTL support via flipForTextDirection for internationalization