# Split button

One safe default action with a menu of related ones: a button and a caret button joined into one bar, the caret opening the menu.

Block: `smbk-split-button`. Status: experimental. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.

## Options

| Axis | Values | Default | Meaning |
|---|---|---|---|
| `tone` | `brand`, `secondary`, `outline` | `brand` | The action family of both buttons and the line between them. There is no danger tone: a destructive default is never hidden behind a menu. |
| `size` | `lg`, `md`, `sm` | `md` | The button’s heights; the caret button is a square of the same height, and the menu’s rows are small under the small size. |



## Markup

```html
<div
  role="group"
  aria-label="Export PDF"
  class="smbk-btn-group smbk-btn-group--type-segmented smbk-btn-group--tone-brand smbk-btn-group--size-md smbk-btn-group--orientation-horizontal smbk-split-button smbk-split-button--tone-brand smbk-split-button--size-md"
>
  <button type="button" class="smbk-btn smbk-btn--tone-brand smbk-btn--size-md">
    <i class="ph ph-file-pdf smbk-icon smbk-icon--size-md smbk-btn__icon" aria-hidden="true"></i>
    <span class="smbk-btn__label">Export PDF</span>
  </button>
  <div class="smbk-dropdown__anchor">
    <button
      type="button"
      class="smbk-btn smbk-btn--tone-brand smbk-btn--size-md smbk-btn--icon-only"
      aria-label="More export options"
      id="split-button-1-opener"
      aria-haspopup="menu"
      aria-expanded="false"
      aria-controls="split-button-1-panel"
    >
      <i
        class="ph ph-caret-down smbk-icon smbk-icon--size-md smbk-btn__icon"
        aria-hidden="true"
      ></i>
    </button>
    <div class="smbk-dropdown__layer">
      <div
        id="split-button-1-panel"
        role="menu"
        aria-label="More export options"
        class="smbk-dropdown smbk-dropdown--size-md smbk-dropdown--align-end"
        tabindex="-1"
        data-scrollbar=""
        hidden=""
      >
        <button type="button" role="menuitem" tabindex="-1" class="smbk-dropdown__item">
          <i
            class="ph ph-file-csv smbk-icon smbk-icon--size-md smbk-dropdown__icon"
            aria-hidden="true"
          ></i>
          <span class="smbk-dropdown__text">Export CSV</span>
        </button>
        <button type="button" role="menuitem" tabindex="-1" class="smbk-dropdown__item">
          <i
            class="ph ph-file-code smbk-icon smbk-icon--size-md smbk-dropdown__icon"
            aria-hidden="true"
          ></i>
          <span class="smbk-dropdown__text">Export JSON</span>
        </button>
        <button type="button" role="menuitem" tabindex="-1" class="smbk-dropdown__item">
          <i
            class="ph ph-file-text smbk-icon smbk-icon--size-md smbk-dropdown__icon"
            aria-hidden="true"
          ></i>
          <span class="smbk-dropdown__text">Export Markdown</span>
        </button>
      </div>
    </div>
  </div>
</div>
```

## React

```tsx
import { SplitButton } from './design-system/components/split-button/split-button.js';
import { DropdownItem } from './design-system/components/dropdown/dropdown.js';

<SplitButton tone="brand" size="md" label="Export PDF" menuLabel="More export options" leadingIcon="FilePdf">
  <DropdownItem icon="FileCsv">Export CSV</DropdownItem>
  <DropdownItem icon="FileCode">Export JSON</DropdownItem>
  <DropdownItem icon="FileText">Export Markdown</DropdownItem>
</SplitButton>
```

## Stylesheet

```css
/* smbk-split-button — Split button. Figma "Split button" 7115:1869: Tone × Size × State, 27 variants.
 * Built on the button group, as Figma builds it: the markup carries the group's segmented classes at the same
 * tone and size as well as this block, so the corners, the hairline between the two buttons and the outline
 * bar's edge are the group's. The first child is the default action, a button; the second the dropdown's anchor,
 * whose opener is an icon-only button with a caret, square at the button's size. The menu hangs under the bar,
 * lined up with its end edge. This sheet adds only what the split button draws differently from a group. */

/* Outline: the line between the action and the caret is the outline edge itself, as strong as the bar's
   outer edge, where a segmented outline bar draws a fainter line between equal choices. */
.smbk-split-button.smbk-split-button--tone-outline:not(.smbk-btn-group--orientation-vertical) > .smbk-btn + .smbk-dropdown__anchor > .smbk-btn {
  border-inline-start-color: var(--smbk-color-action-outline-border);
}
```

## Tokens it reads

```json
{
  "color": {
    "action": {
      "outline": {
        "border": {
          "$type": "color",
          "$value": "{{color.grey.300}}",
          "$description": "Outline button: edge at rest."
        }
      }
    }
  }
}
```

## Purpose

One safe default action with a menu of related ones: "Export PDF", with CSV and JSON in the menu. The main button runs the default at once; the caret button beside it opens the menu of alternatives. It differs from a button that only opens a menu, where every choice is behind the menu, and from a button group, where every action is in view.

## Anatomy

- The block, a segmented button group: the markup has the group's classes at the same tone and size as well as this block's, so the joined corners and the line between the two buttons are the group's.
- The default action, a button with its words and an optional icon before them.
- The caret button, an icon-only button with a caret, square at the button's height. It points down, and up while the menu is open.
- The menu, a dropdown that hangs under the bar, lined up with its end edge. Its rows are small under the small size.

## When to use

- One action most people want, with a few close variations: export in another format, save in another way, send later.
- When the default must stay one press away while the alternatives stay out of sight.

## When not to use

- When no choice is clearly the default. Use a [button](button.md) that opens a menu.
- When every action matters equally and fits. Use a [button group](button-group.md).
- For a destructive default. There is no danger tone: never hide a destructive action behind the menu or make it the default.

## Behavior

Pressing the main button runs the default action without opening the menu. Pressing the caret button opens the menu under the bar, lined up with its end edge; choosing an item runs it and closes the menu. A click outside or Escape closes it. Disabled, both buttons dim and neither can be pressed.

Three tones: brand, secondary and outline. In the outline tone the line between the two buttons is as strong as the outer edge.

## Accessibility
### What it does for you

- It is a group of two real buttons, named by the default action's words, and two stops in the tab order: the action, then the caret.
- The caret button says it opens a menu and whether it is open.
- The menu's keyboard is the dropdown's: Enter, Space or the down arrow open it on its first item, the arrows move between items, Escape closes it and puts focus back on the caret button.
- Each button keeps its own focus ring, which the joined edge never hides.
- The row mirrors for right-to-left languages.

### What you must do

- Give the caret button a name of its own that says what the menu holds, such as "More export options". It must differ from the action's words; the wrapper warns in development when it does not, since a screen reader would hear two buttons with one name.

### How to test

- Tab: focus lands on the action, then the caret, each with its focus ring in both themes and in a forced-color mode.
- On the caret, press Enter, Space or the down arrow: the menu opens on its first item. Arrow between items, press Enter to choose one, and press Escape to close it with focus back on the caret.
- With a screen reader, the two buttons are read with different names, and the caret as a menu button that is open or closed.

### Keyboard

| Key | What it does |
|---|---|
| Tab | Moves focus to the action, then to the caret button. |
| Enter or Space | On the action, runs it. On the caret button, opens the menu on its first item. |
| Down Arrow | On the caret button, opens the menu on its first item. In the menu, moves to the next item. |
| Up Arrow | In the menu, moves to the previous item. |
| Escape | Closes the menu and puts focus back on the caret button. |

## Usage rules

### Do

- Make the default the action most people want.
- Name the caret button for what the menu holds.
- Keep the menu short: the close alternatives, not every action on the page.

### Don't

- Repeat the default action in the menu.
- Put a destructive action as the default.
- Use it when there is no clear default.