# SplitButton

> A primary action joined to a menu of closely related alternatives.

Category: Actions · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/split-button

Use SplitButton when one action is the clear default but a few variations are useful, such as “Deploy signatures” with “Schedule deployment”. The left half performs the default; the right half opens a DropdownMenu. If the actions are equally important, use a ButtonGroup or separate buttons instead.

## Import

```tsx
import { SplitButton, DropdownMenuItem } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { DropdownMenuItem, DropdownMenuSeparator, Icon, SplitButton } from '@bindshq/stance-react';

export function Basic() {
  return (
    <SplitButton
      leadingIcon={<Icon name="send" />}
      menuLabel="More deployment options"
      menu={
        <>
          <DropdownMenuItem icon={<Icon name="clock" />}>Schedule deployment</DropdownMenuItem>
          <DropdownMenuItem icon={<Icon name="users" />}>Deploy to selected users</DropdownMenuItem>
          <DropdownMenuSeparator />
          <DropdownMenuItem icon={<Icon name="eye" />}>Preview changes</DropdownMenuItem>
        </>
      }
    >
      Deploy signatures
    </SplitButton>
  );
}
```

### Variants

```tsx
import { DropdownMenuItem, SplitButton } from '@bindshq/stance-react';

export function Variants() {
  const menu = (
    <>
      <DropdownMenuItem>Save as draft</DropdownMenuItem>
      <DropdownMenuItem>Save as new template</DropdownMenuItem>
    </>
  );
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <SplitButton menu={menu}>Save</SplitButton>
      <SplitButton variant="secondary" menu={menu}>
        Save
      </SplitButton>
      <SplitButton variant="outline" menu={menu}>
        Save
      </SplitButton>
    </div>
  );
}
```

### Sizes

```tsx
import { DropdownMenuItem, SplitButton } from '@bindshq/stance-react';

export function Sizes() {
  const menu = <DropdownMenuItem>Export as PNG</DropdownMenuItem>;
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12 }}>
      <SplitButton size="xs" variant="outline" menu={menu}>
        Export
      </SplitButton>
      <SplitButton size="sm" variant="outline" menu={menu}>
        Export
      </SplitButton>
      <SplitButton size="md" variant="outline" menu={menu}>
        Export
      </SplitButton>
      <SplitButton size="lg" variant="outline" menu={menu}>
        Export
      </SplitButton>
    </div>
  );
}
```

### Loading and disabled

```tsx
import { DropdownMenuItem, SplitButton } from '@bindshq/stance-react';

export function States() {
  const menu = <DropdownMenuItem>Retry failed only</DropdownMenuItem>;
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <SplitButton loading menu={menu}>
        Syncing users
      </SplitButton>
      <SplitButton disabled menu={menu}>
        Sync users
      </SplitButton>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SplitButton | `children` (required) | `ReactNode` | None | Label of the primary action. |
| SplitButton | `onClick` | `MouseEventHandler` | None | Runs the primary action. |
| SplitButton | `menu` (required) | `ReactNode` | None | DropdownMenuItem elements for the alternatives. |
| SplitButton | `variant` | `'primary' \| 'secondary' \| 'outline'` | `'primary'` | Visual emphasis for both halves. |
| SplitButton | `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
| SplitButton | `menuLabel` | `string` | `'More options'` | Accessible label of the menu toggle. |
| SplitButton | `menuAlign` | `'start' \| 'center' \| 'end'` | `'end'` | Menu alignment. |
| SplitButton | `menuDisabled` | `boolean` | `false` | Disable only the toggle. |
| SplitButton | `disabled / loading / leadingIcon` | `None` | None | As Button, applied to the primary half (disabled applies to both). |

## Accessibility

- Both halves are native buttons inside a role="group"; the toggle has its own accessible label and aria-haspopup="menu".
- Each half is a separate tab stop so keyboard users can reach either directly.
- The menu inherits the full DropdownMenu keyboard model.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Move between the action and the menu toggle. |
| `Enter` `Space` | Run the action, or open the menu from the toggle. |
| `ArrowDown` | On the toggle: open the menu. |

## Guidelines

**Do**

- Keep alternatives closely related to the primary action.
- Label the toggle descriptively when there are several split buttons.

**Don’t**

- Put unrelated or destructive actions in the menu.

## Related

- https://stanceui.com/components/button
- https://stanceui.com/components/dropdown-menu
- https://stanceui.com/components/button-group