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.
Options
| Choice | Values | Default | What it does |
|---|---|---|---|
tonesmbk-split-button--tone-<value> | brandsecondaryoutline | 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. |
sizesmbk-split-button--size-<value> | lgmdsm | 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. |
Examples
Usage
The default action runs at once; the caret opens the alternatives. Press the caret, or Tab to it and press Enter or the down arrow; Escape closes the menu.
Tones
Brand, secondary and outline. There is no danger tone: a destructive default is never hidden behind a menu.
Sizes
The button’s three heights; the caret button is a square of the same height, and the menu’s rows are small under the small size.
Disabled
Both buttons dim and neither can be pressed.
Guidelines
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.
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 that opens a menu.
- When every action matters equally and fits. Use a button group.
- For a destructive default. There is no danger tone: never hide a destructive action behind the menu or make it the default.
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.
Name the caret for what its menu holds, so a screen reader can tell the two buttons apart.
A split button with no clear default makes the reader open the menu anyway; use a button that opens a menu.
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.
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. |
| EnterorSpace | 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. |
Source
The files the split button is made of. Its folder on GitHub (opens in a new tab) holds them with its wrapper and its document.
Stylesheet
/* 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
| Token and CSS | Value | Preview | Foundation |
|---|---|---|---|
| color.action.outline.border--smbk-color-action-outline-border | light: #c4cdd8dark: #373d43changes with theme | Color |
Manifest
{
"name": "split-button",
"block": "smbk-split-button",
"summary": "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.",
"adapt": "css",
"axes": {
"tone": {
"values": [
"brand",
"secondary",
"outline"
],
"default": "brand",
"description": "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": {
"values": [
"lg",
"md",
"sm"
],
"default": "md",
"description": "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."
}
},
"flags": {},
"parts": [],
"figmaNodeId": "7115:1869"
}