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.
- 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.
- The actions are equally important. Show separate
Buttons or a ButtonGroup.
- The menu needs long explanatory content. Promote to a
Modal 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.
- 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.
- 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.
Do
- 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.
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.
- Modal for destructive confirmations after a menu selection.
