Spectrum 2 is now available! Check out the S2 ButtonGroup docs and the migration docs.

ButtonGroup

ButtonGroup handles overflow for a grouping of buttons whose actions are related to each other.

install	`yarn add @adobe/react-spectrum`
added	3.0.0
usage	`import {ButtonGroup} from '@adobe/react-spectrum'`

View guidelines

Example#

import {Button, ButtonGroup} from '@adobe/react-spectrum';

<ButtonGroup>
  <Button variant="primary">Rate Now</Button>
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
</ButtonGroup>

import {Button, ButtonGroup} from '@adobe/react-spectrum';

<ButtonGroup>
  <Button variant="primary">Rate Now</Button>
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
</ButtonGroup>

import {
  Button,
  ButtonGroup
} from '@adobe/react-spectrum';

<ButtonGroup>
  <Button variant="primary">
    Rate Now
  </Button>
  <Button variant="secondary">
    No, thanks
  </Button>
  <Button variant="secondary">
    Remind me later
  </Button>
</ButtonGroup>

Content#

ButtonGroup expects Buttons as children and is used to handle overflow. When horizontal space is limited, the ButtonGroup switches to a vertical layout. ButtonGroup should be used when there are two or more related Buttons in a group. To see the orientation switch in the example above, resize the width of your window.

Props#

Name	Type	Default	Description
`children`	`ReactNode`	—	The Buttons contained within the ButtonGroup.
`isDisabled`	`boolean`	—	Whether the Buttons in the ButtonGroup are all disabled.
`orientation`	`Orientation`	`'horizontal'`	The axis the ButtonGroup should align with. Setting this to 'vertical' will prevent any switching behaviors between 'vertical' and 'horizontal'.
`align`	`Alignment \| 'center'`	`'start'`	The alignment of the buttons within the ButtonGroup.

Layout

Name	Type	Description
`flex`	`Responsive<string \| number \| boolean>`	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`Responsive<number>`	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`Responsive<number>`	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`Responsive<number \| string>`	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'>`	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'>`	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`Responsive<number>`	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`Responsive<string>`	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`Responsive<string>`	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`Responsive<string>`	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`Responsive<string>`	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`Responsive<string>`	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`Responsive<string>`	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`Responsive<string>`	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Description
`margin`	`Responsive<DimensionValue>`	The margin for all four sides of the element. See MDN.
`marginTop`	`Responsive<DimensionValue>`	The margin for the top side of the element. See MDN.
`marginBottom`	`Responsive<DimensionValue>`	The margin for the bottom side of the element. See MDN.
`marginStart`	`Responsive<DimensionValue>`	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`Responsive<DimensionValue>`	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`Responsive<DimensionValue>`	The margin for both the left and right sides of the element. See MDN.
`marginY`	`Responsive<DimensionValue>`	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Description
`width`	`Responsive<DimensionValue>`	The width of the element. See MDN.
`minWidth`	`Responsive<DimensionValue>`	The minimum width of the element. See MDN.
`maxWidth`	`Responsive<DimensionValue>`	The maximum width of the element. See MDN.
`height`	`Responsive<DimensionValue>`	The height of the element. See MDN.
`minHeight`	`Responsive<DimensionValue>`	The minimum height of the element. See MDN.
`maxHeight`	`Responsive<DimensionValue>`	The maximum height of the element. See MDN.

Positioning

Name	Type	Description
`position`	`Responsive<'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'>`	Specifies how the element is positioned. See MDN.
`top`	`Responsive<DimensionValue>`	The top position for the element. See MDN.
`bottom`	`Responsive<DimensionValue>`	The bottom position for the element. See MDN.
`left`	`Responsive<DimensionValue>`	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`Responsive<DimensionValue>`	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`Responsive<DimensionValue>`	The logical start position for the element, depending on layout direction. See MDN.
`end`	`Responsive<DimensionValue>`	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`Responsive<number>`	The stacking order for the element. See MDN.
`isHidden`	`Responsive<boolean>`	Hides the element.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.

Advanced

Name	Type	Description
`UNSAFE_className`	`string`	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Orientation#

View guidelines

Setting this to 'vertical' will prevent any dynamic orientation changes, the ButtonGroup will remain in vertical regardless of the available width.

<ButtonGroup orientation="vertical">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup orientation="vertical">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup orientation="vertical">
  <Button variant="secondary">
    No, thanks
  </Button>
  <Button variant="secondary">
    Remind me later
  </Button>
  <Button variant="primary">
    Rate Now
  </Button>
</ButtonGroup>

Alignment#

View guidelines

Button groups are aligned contextually. Generally, button groups should be start-aligned to follow content. However, they should be end-aligned inside container components, such as in dialogs, popovers, or cards. Center alignment should be used in the context of an empty state. In right-to-left languages, alignment is flipped automatically.

<ButtonGroup orientation="vertical" align="end">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup orientation="vertical" align="end">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup
  orientation="vertical"
  align="end"
>
  <Button variant="secondary">
    No, thanks
  </Button>
  <Button variant="secondary">
    Remind me later
  </Button>
  <Button variant="primary">
    Rate Now
  </Button>
</ButtonGroup>

<ButtonGroup orientation="vertical" align="center">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup orientation="vertical" align="center">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup
  orientation="vertical"
  align="center"
>
  <Button variant="secondary">
    No, thanks
  </Button>
  <Button variant="secondary">
    Remind me later
  </Button>
  <Button variant="primary">
    Rate Now
  </Button>
</ButtonGroup>

Disabled#

View guidelines

<ButtonGroup isDisabled>
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup isDisabled>
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup
  isDisabled
>
  <Button variant="secondary">
    No, thanks
  </Button>
  <Button variant="secondary">
    Remind me later
  </Button>
  <Button variant="primary">
    Rate Now
  </Button>
</ButtonGroup>