# ButtonGroup

Lays out the actions at the foot of a dialog or focused flow.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/ButtonGroup.tsx)

Figma: [Button Group](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1269-1089)

## Overview

A button group places [Buttons](/docs/components/button) side by side at equal widths, or stacks them at full width.

## Examples

### Basic

```tsx
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <ButtonGroup {...styles.group()}>
      <Button size="large" variant="secondary">
        Cancel
      </Button>
      <Button size="large">Confirm</Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '360', width: '100% !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ButtonGroup/Basic.tsx)

### Orientation

Set `orientation` to `horizontal` (default) or `vertical`. Both place the buttons 8px apart.

```tsx
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <ButtonGroup orientation="vertical" {...styles.group()}>
      <Button size="large">Get started</Button>
      <Button size="large" variant="tertiary">
        Not now
      </Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '360', width: '100% !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ButtonGroup/Orientation.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Button, ButtonGroup } from '@tempoxyz/ds'

<ButtonGroup>
  <Button />
</ButtonGroup>
```

## Guidelines

### When to Use

* Close a dialog with two actions of equal weight, such as Cancel and Confirm.
* Stack a main action above a dismiss action in an intro or announcement, such as Get started and Not now.

### When Not to Use

* Use a [SplitButton](/docs/components/split-button) for a main action with related alternatives.
* Use an [Inline](/docs/components/inline) row for actions at their natural width, such as a toolbar.
* Use a [Menu](/docs/components/menu) for more than three actions.

### Put the Primary Action Last

Place the `primary` action on the right of a pair. Keep the source order the same as the visual order, so focus reaches the main action last.

**Do:** Put the `secondary` action first and the `primary` action last.

```tsx
/**
 * Do example for "Put the Primary Action Last" on the ButtonGroup page.
 * Put the `secondary` action first and the `primary` action last.
 * @module
 */
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ButtonGroup {...styles.group()}>
      <Button size="large" variant="secondary">
        Cancel
      </Button>
      <Button size="large">Confirm</Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320', width: '100% !custom' })
}
```

**Don't:** Put the `primary` action on the left of a pair.

```tsx
/**
 * Don't example for "Put the Primary Action Last" on the ButtonGroup page.
 * Don't put the `primary` action on the left of a pair.
 * @module
 */
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ButtonGroup {...styles.group()}>
      <Button size="large">Confirm</Button>
      <Button size="large" variant="secondary">
        Cancel
      </Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320', width: '100% !custom' })
}
```

### Keep Every Button the Same Size

Give every button in a dialog footer the `large` size. In a stack, the `tertiary` dismiss action keeps that size.

**Do:** Give the dismiss action the same `large` size as the `primary` action.

```tsx
/**
 * Do example for "Keep Every Button the Same Size" on the ButtonGroup page.
 * Give the dismiss action the same `large` size as the `primary` action.
 * @module
 */
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ButtonGroup orientation="vertical" {...styles.group()}>
      <Button size="large">Get started</Button>
      <Button size="large" variant="tertiary">
        Not now
      </Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320', width: '100% !custom' })
}
```

**Don't:** Shrink the dismiss action below the `primary` action.

```tsx
/**
 * Don't example for "Keep Every Button the Same Size" on the ButtonGroup page.
 * Don't shrink the dismiss action below the `primary` action.
 * @module
 */
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ButtonGroup orientation="vertical" {...styles.group()}>
      <Button size="large">Get started</Button>
      <Button size="small" variant="tertiary">
        Not now
      </Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320', width: '100% !custom' })
}
```

## Content

### Name the Destructive Action

If the action destroys data or removes access, name what it does on the `primary` button, such as Revoke all.

**Do:** Name both outcomes, such as Keep keys and Revoke all.

```tsx
/**
 * Do example for "Name the Destructive Action" on the ButtonGroup page.
 * Name both outcomes, such as Keep keys and Revoke all.
 * @module
 */
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ButtonGroup {...styles.group()}>
      <Button size="large" variant="secondary">
        Keep keys
      </Button>
      <Button size="large">Revoke all</Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320', width: '100% !custom' })
}
```

**Don't:** Label a destructive action OK.

```tsx
/**
 * Don't example for "Name the Destructive Action" on the ButtonGroup page.
 * Don't label a destructive action OK.
 * @module
 */
import { Button, ButtonGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ButtonGroup {...styles.group()}>
      <Button size="large" variant="secondary">
        Cancel
      </Button>
      <Button size="large">OK</Button>
    </ButtonGroup>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320', width: '100% !custom' })
}
```

## Accessibility

`ButtonGroup` renders a `div` with `role="group"` around native buttons. See [Accessibility](/docs/foundations/accessibility) for the baseline.

* **Group (group):** Groups the actions. Name it with `aria-label` when the dialog title does not.
* **Focus Order (Tab):** Follows the source order, which matches the visual order in both orientations.
* **Target Size (48px):** Large buttons stretch to the full width, which leaves a wide target on touch screens.

## Related

[Button](/docs/components/button)

Use for each action in the group.

[Dialog](/docs/components/dialog)

Use for the focused task that the group closes.

[AlertDialog](/docs/components/alert-dialog)

Use for confirming a destructive action.
