# SplitButton

Pairs a primary action with a menu of alternatives.

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

## Overview

A split button places the most common action beside a trigger that opens a menu of alternatives.

## Examples

### Basic

```tsx
import { Menu, SplitButton } from '@tempoxyz/ds'

export function Demo() {
  return (
    <SplitButton.Root aria-label="Save">
      <SplitButton.Action>Save</SplitButton.Action>
      <Menu.Root>
        <SplitButton.Trigger aria-label="More save options" />
        <Menu.Popup align="end">
          <Menu.Item>Save as draft</Menu.Item>
          <Menu.Item>Save and close</Menu.Item>
        </Menu.Popup>
      </Menu.Root>
    </SplitButton.Root>
  )
}
```

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

### Variant

Set `variant` on `SplitButton.Root` to `primary` (default), `secondary`, or `tertiary`.

```tsx
import { Menu, SplitButton, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
        <SplitButton.Root key={variant} variant={variant}>
          <SplitButton.Action>Save</SplitButton.Action>
          <Menu.Root>
            <SplitButton.Trigger aria-label="More save options" />
            <Menu.Popup align="end">
              <Menu.Item>Save as draft</Menu.Item>
              <Menu.Item>Save and close</Menu.Item>
            </Menu.Popup>
          </Menu.Root>
        </SplitButton.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

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

## Anatomy

Import the component and assemble its parts.

```tsx
import { Menu, SplitButton } from '@tempoxyz/ds'

<SplitButton.Root>
  <SplitButton.Action />
  <Menu.Root>
    <SplitButton.Trigger />
    <Menu.Popup />
  </Menu.Root>
</SplitButton.Root>
```

## Guidelines

### When to Use

* Offer a main action with a few variations, such as Export CSV with Export JSON and Schedule export.
* Keep the common choice one press away, such as Create key with Create test key.

### When Not to Use

* Use a [Button](/docs/components/button) with a [Menu](/docs/components/menu) when no option is the clear default.
* Use two [Buttons](/docs/components/button) when both actions matter equally.
* Use [Select](/docs/components/select) or [ChoiceGroup](/docs/components/choice-group) to choose a value or mode, not to run an action.
* Use a separate [Button](/docs/components/button) for destructive actions, confirmed with an [AlertDialog](/docs/components/alert-dialog).

### Make the Action the Common Choice

`SplitButton.Action` runs without opening the menu, so give it the option most people pick. If people often open the menu first, move the popular option into the action, or use a [Menu](/docs/components/menu) button.

**Do:** Put the option most people pick on the action.

```tsx
/**
 * Do example for "Make the Action the Common Choice" on the SplitButton page.
 * Put the option most people pick on the action.
 * @module
 */
import { Menu, SplitButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <SplitButton.Root aria-label="Keys">
        <SplitButton.Action>Create key</SplitButton.Action>
        <Menu.Root>
          <SplitButton.Trigger aria-label="More key options" />
        </Menu.Root>
      </SplitButton.Root>
      <div {...styles.popup()}>
        <div {...styles.item()}>Create test key</div>
        <div {...styles.item()}>Import key</div>
      </div>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    borderRadius: 'xs',
    color: 'content.primary',
    display: 'flex',
    minHeight: '40',
    paddingInline: '12',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    minWidth: '14rem !custom',
    padding: '12',
  })

  export const stack = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '4',
  })
}
```

**Don't:** Put a rare option on the action and the common one in the menu.

```tsx
/**
 * Don't example for "Make the Action the Common Choice" on the SplitButton page.
 * Don't put a rare option on the action and the common one in the menu.
 * @module
 */
import { Menu, SplitButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <SplitButton.Root aria-label="Keys">
        <SplitButton.Action>Import key</SplitButton.Action>
        <Menu.Root>
          <SplitButton.Trigger aria-label="More key options" />
        </Menu.Root>
      </SplitButton.Root>
      <div {...styles.popup()}>
        <div {...styles.item()}>Create key</div>
        <div {...styles.item()}>Create test key</div>
      </div>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    borderRadius: 'xs',
    color: 'content.primary',
    display: 'flex',
    minHeight: '40',
    paddingInline: '12',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    minWidth: '14rem !custom',
    padding: '12',
  })

  export const stack = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '4',
  })
}
```

### Keep Alternatives Related

Make every menu item a variation of the action, such as a different format or timing, and use two to five of them. Put unrelated commands, or a longer list, in a [Menu](/docs/components/menu).

**Do:** Fill the menu with variations of the main action.

```tsx
/**
 * Do example for "Keep Alternatives Related" on the SplitButton page.
 * Fill the menu with variations of the main action.
 * @module
 */
import { Menu, SplitButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <SplitButton.Root aria-label="Export" variant="secondary">
        <SplitButton.Action>Export CSV</SplitButton.Action>
        <Menu.Root>
          <SplitButton.Trigger aria-label="More export options" />
        </Menu.Root>
      </SplitButton.Root>
      <div {...styles.popup()}>
        <div {...styles.item()}>Export JSON</div>
        <div {...styles.item()}>Schedule export</div>
      </div>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    borderRadius: 'xs',
    color: 'content.primary',
    display: 'flex',
    minHeight: '40',
    paddingInline: '12',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    minWidth: '14rem !custom',
    padding: '12',
  })

  export const stack = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '4',
  })
}
```

**Don't:** Collect unrelated or destructive commands behind the trigger.

```tsx
/**
 * Don't example for "Keep Alternatives Related" on the SplitButton page.
 * Don't collect unrelated or destructive commands behind the trigger.
 * @module
 */
import { Menu, SplitButton, style, variants } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <SplitButton.Root aria-label="Export" variant="secondary">
        <SplitButton.Action>Export CSV</SplitButton.Action>
        <Menu.Root>
          <SplitButton.Trigger aria-label="More options" />
        </Menu.Root>
      </SplitButton.Root>
      <div {...styles.popup()}>
        <div {...styles.item()}>Rename dashboard</div>
        <div {...styles.item()}>Share</div>
        <div {...styles.item({ intent: 'negative' })}>Delete dashboard</div>
      </div>
    </div>
  )
}

namespace styles {
  export const item = variants({
    base: {
      alignItems: 'center',
      borderRadius: 'xs',
      color: 'content.primary',
      display: 'flex',
      minHeight: '40',
      paddingInline: '12',
      typography: 'body.b2Strong',
    },
    defaultVariants: { intent: 'default' },
    variants: {
      intent: {
        default: {},
        negative: { color: 'content.negative' },
      },
    },
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    minWidth: '14rem !custom',
    padding: '12',
  })

  export const stack = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '4',
  })
}
```

### Match the Buttons Around It

Set `variant` and `size` on `SplitButton.Root`, and both buttons follow. A split button counts toward the one `primary` action per section, so use `secondary` when the view already has one. Use `small` in toolbars and table headers.

**Do:** Match the size of nearby buttons, and leave `primary` to the main action.

```tsx
/**
 * Do example for "Match the Buttons Around It" on the SplitButton page.
 * Match the size of nearby buttons, and leave `primary` to the main action.
 * @module
 */
import { Button, Menu, SplitButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <SplitButton.Root aria-label="Export" size="small" variant="secondary">
        <SplitButton.Action>Export CSV</SplitButton.Action>
        <Menu.Root>
          <SplitButton.Trigger aria-label="More export options" />
        </Menu.Root>
      </SplitButton.Root>
      <Button size="small">Send payment</Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

**Don't:** Add a second `primary` action, or a size that differs from its neighbors.

```tsx
/**
 * Don't example for "Match the Buttons Around It" on the SplitButton page.
 * Don't add a second `primary` action, or a size that differs from its neighbors.
 * @module
 */
import { Button, Menu, SplitButton, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <SplitButton.Root aria-label="Export">
        <SplitButton.Action>Export CSV</SplitButton.Action>
        <Menu.Root>
          <SplitButton.Trigger aria-label="More export options" />
        </Menu.Root>
      </SplitButton.Root>
      <Button size="small">Send payment</Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

## Content

### Name the Action and Its Object

Label `SplitButton.Action` with a verb and an object, such as Export CSV. A bare Export hides which variation runs.

### Make Each Item Stand Alone

Repeat the verb in each menu item, such as Export JSON, not JSON, so each item reads as a complete action.

## Accessibility

`SplitButton` renders a group with a primary [Button](/docs/components/button) and a menu trigger. The trigger follows the [WAI-ARIA menu button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/).

### Semantics

* **SplitButton.Root (group):** Holds both buttons, named by its `aria-label`.
* **SplitButton.Action (button):** The primary action, as a native button.
* **SplitButton.Trigger (aria-haspopup):** A native button that announces its menu and open state.
* **Menu (menu):** Named by the trigger. Items are announced as menu items.
* **Chevron (reduced motion):** Rotates while the menu is open. Flips without animation under reduced motion.

### Keyboard

* **Move Between Buttons (Tab):** Moves focus to the action, then to the trigger.
* **Run the Action (Enter or Space):** On the action, runs the primary action.
* **Open to the First Item (Enter, Space, or Down Arrow):** Opens the menu and focuses the first item.
* **Open to the Last Item (Up Arrow):** Opens the menu and focuses the last item.
* **Move Between Items (Down Arrow and Up Arrow):** Move between items, and wrap at the ends.
* **Jump to the Ends (Home and End):** Move to the first and last item.
* **Activate an Item (Enter):** Activates the focused item and closes the menu.
* **Close the Menu (Escape):** Closes the menu.

### Your Responsibilities

* **Name the Group (aria-label):** Name the root, such as "Save", so the pair reads as one group.
* **Name the Trigger (aria-label):** Name the alternatives, such as "More save options". The chevron is the trigger's only content.
* **Keep Actions Reachable:** If the primary action fails or is disabled, keep every menu action reachable another way.

## Related

[Button](/docs/components/button)

Use for single actions.

[Menu](/docs/components/menu)

Use for lists of actions without a default.

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

Use for confirming destructive actions.

[Forms](/docs/patterns/forms)

Covers placing actions.
