Split button

Usage

Overview

SplitButton pairs a default action with a menu of related alternates—"Export" as the common commit, with "Export CSV", "Export PDF", and "Export JSON" behind the chevron. It communicates hierarchy directly: the main click is the happy path, the chevron reveals depth. Use it instead of faking a ButtonGroup with a mystery icon, and keep the alternates related—if the menu's verbs don't share the primary's intent, the control has become two controls.

When to use

A clear primary action exists most of the time and related variants belong adjacent to it (export patterns, save/save-as, send now/send later).
Horizontal space is tighter than showing a separate labeled button per variant.
The menu is short—roughly five or fewer entries—and all the entries share the primary's verb family.

When not to use

The actions are equally important. Show separate Buttons or a ButtonGroup.
The menu needs long explanatory content. Promote to a Dialog or a side panel.
Mobile-primary flows where the split target is hard to tap. Use a single primary plus a full-width Menu sheet.
The menu would include destructive and constructive actions side by side without isolation. Separate surfaces communicate better.

Content guidelines

Primary label uses title case, active verbs per the Button standards; menu items parallel that voice. Localize every string with formatMessage.
Destructive entries belong at the bottom of the menu, separated from the rest, with explicit wording ("Delete permanently").
Keep primary and menu labels distinct enough that the menu actually differentiates from the primary click.

Behavior and states

Menu alignment. menuAlign keeps the chevron visually attached to its menu. Pick the alignment that matches reading order and avoids clipping inside sticky toolbars.
Disabled. Disable both segments together when the control is invalid. Partial disable needs design approval because it breaks the "primary plus related" contract.
Loading. A loading primary should not leave the menu enabled when the menu items would race the primary. Disable the chevron while the primary resolves when the actions conflict.

Best practices

Reserve the primary click for the safest common path. Destructive actions live in the menu with confirmation downstream.
Keep the menu short. Move advanced flows to dedicated pages or settings.
Match the chevron side to the menu side so the menu doesn't jump across the button when it opens.

Don't

Nest split buttons inside split buttons. The disclosure pattern stops being disclosure.
Use when operators can't discover the menu. If the alternates are critical, expose them in training or a visible help entry.
Make the primary and menu labels identical. The primary becomes a duplicate click.

Accessibility

Both segments need individual accessible names; the chevron is not the only hint. Keyboard users must open the menu and navigate items predictably. See Accessibility for the full contract.

Button for emphasis rules.
Button group for peer actions.
Menu for menu content patterns.
Dialog for destructive confirmations after a menu selection.

Sources / Accessibility

Split button / API and Development

On this page

Split button

Usage

Overview

When to use

A clear primary action exists most of the time and related variants belong adjacent to it (export patterns, save/save-as, send now/send later).
Horizontal space is tighter than showing a separate labeled button per variant.
The menu is short—roughly five or fewer entries—and all the entries share the primary's verb family.

When not to use

The actions are equally important. Show separate Buttons or a ButtonGroup.
The menu needs long explanatory content. Promote to a Dialog or a side panel.
Mobile-primary flows where the split target is hard to tap. Use a single primary plus a full-width Menu sheet.
The menu would include destructive and constructive actions side by side without isolation. Separate surfaces communicate better.

Content guidelines

Primary label uses title case, active verbs per the Button standards; menu items parallel that voice. Localize every string with formatMessage.
Destructive entries belong at the bottom of the menu, separated from the rest, with explicit wording ("Delete permanently").
Keep primary and menu labels distinct enough that the menu actually differentiates from the primary click.

Behavior and states

Menu alignment. menuAlign keeps the chevron visually attached to its menu. Pick the alignment that matches reading order and avoids clipping inside sticky toolbars.
Disabled. Disable both segments together when the control is invalid. Partial disable needs design approval because it breaks the "primary plus related" contract.
Loading. A loading primary should not leave the menu enabled when the menu items would race the primary. Disable the chevron while the primary resolves when the actions conflict.

Best practices

Reserve the primary click for the safest common path. Destructive actions live in the menu with confirmation downstream.
Keep the menu short. Move advanced flows to dedicated pages or settings.
Match the chevron side to the menu side so the menu doesn't jump across the button when it opens.

Don't

Nest split buttons inside split buttons. The disclosure pattern stops being disclosure.
Use when operators can't discover the menu. If the alternates are critical, expose them in training or a visible help entry.
Make the primary and menu labels identical. The primary becomes a duplicate click.

Accessibility

Both segments need individual accessible names; the chevron is not the only hint. Keyboard users must open the menu and navigate items predictably. See Accessibility for the full contract.

Button for emphasis rules.
Button group for peer actions.
Menu for menu content patterns.
Dialog for destructive confirmations after a menu selection.

Sources / Accessibility

Split button / API and Development

On this page