Axon 911 Frontend DocsAxon 911 Frontend Docs
Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Components
  3. Split Button
  5. Usage

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.
Reset zoom to 100%
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.
  • Divider. One hairline separates the primary from the chevron, runs the inner height of the control and meets the single tray edge stroke without overlapping it. It stays visible while either segment is hovered or pressed, because it is the only cue that the two segments are separate targets. A ButtonGroup fades its short dividers beside a hovered segment; SplitButton opts out through persistentDivider.
  • 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
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.
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.
Related Components
  • Button for emphasis rules.
  • Button group for peer actions.
  • Menu for menu content patterns.
  • Dialog for destructive confirmations after a menu selection.
Previous
Sources / Accessibility
Next
Split button / API and Development
On this page
Overview
When to use
When not to use
Content guidelines
Behavior and states
Best practices
Accessibility
Related Components