---
title: Button group
description: Use the button group component to group related buttons and action menus together.
keywords: ['buttons', 'control', 'action', 'group', 'paired']
ready: true
source: https://github.com/primer/brand/blob/main/packages/react/src/ButtonGroup/ButtonGroup.tsx
storybook: '/brand/storybook/?path=/story/components-buttongroup--playground'
---

```js
import {ActionMenu, Button, ButtonGroup, IconButton} from '@primer/react-brand'
```

## Examples

### Default

This is the default variant for the ButtonGroup component. The first item in the group uses the primary button variant and the second uses the secondary button variant.

```jsx
<ButtonGroup>
  <Button>This is one button</Button>
  <Button>This is another button</Button>
</ButtonGroup>
```

### Joined buttons and icon buttons

Set `variant="joined"` to connect any number of `Button` and `IconButton` children. Joined controls use the `secondary` variant by default so they share one visual hierarchy; explicit child variants override that default.

```jsx
<Stack direction="vertical" alignItems="flex-start" gap="condensed">
  <ButtonGroup variant="joined">
    <Button>Previous</Button>
    <Button>Today</Button>
    <Button>Next</Button>
  </ButtonGroup>
  <ButtonGroup variant="joined">
    <IconButton icon={DownloadIcon} aria-label="Download" />
    <IconButton icon={ShareIcon} aria-label="Share" />
    <IconButton icon={KebabHorizontalIcon} aria-label="More actions" />
  </ButtonGroup>
</Stack>
```

### Action menus

The default ButtonGroup variant supports up to two children and applies `primary` to the first action and `secondary` to the second. Joined groups support any number of `Button` and `IconButton` children. `ActionMenu` is supported only by the default variant.

Explicit `variant` overrides to `Button` or `ActionMenu.Button` will override the default values.

`buttonSize` applies to both child types. Because `ActionMenu` supports only `small` and `medium`, it remains `medium` when `buttonSize="large"`. Set `size` on `ActionMenu` to override the inherited size.

```jsx
<ButtonGroup>
  <Button>Primary action</Button>
  <ActionMenu>
    <ActionMenu.Button>More actions</ActionMenu.Button>
    <ActionMenu.Overlay aria-label="More actions">
      <ActionMenu.Item value="contact-sales">Contact sales</ActionMenu.Item>
      <ActionMenu.Item value="view-pricing">View pricing</ActionMenu.Item>
    </ActionMenu.Overlay>
  </ActionMenu>
</ButtonGroup>
```

### Sizes

The ButtonGroup component supports `small`, `medium`, and `large` buttons. The default size is `medium`. ActionMenu children support `small` and `medium`.

```jsx
<ButtonGroup buttonSize="large">
  <Button>This is one large button</Button>
  <Button>This is another large button</Button>
</ButtonGroup>
```

### Polymorphism

The `Button` component can render as a `button` or `a` HTML element. By default, it will render as a `button`.

```jsx
<ButtonGroup>
  <Button as="a" href="#">
    This is one link
  </Button>
  <Button as="a" href="#">
    This is another link
  </Button>
</ButtonGroup>
```

## Component props

### ButtonGroup

| Name         | Type                             |   Default   | Description                             |
| :----------- | :------------------------------- | :---------: | :-------------------------------------- |
| `buttonSize` | `'small' \| 'medium' \| 'large'` |  `'medium'` | The size variations available in Button |
| `buttonsAs`  | `'button' \| 'a'`                |  `'button'` | The HTML variations available in Button |
| `variant`    | `ButtonGroupVariants`            | `'default'` | The visual presentation of the group    |