SplitButton

A primary action paired with a menu button for related actions.

Overview Api

Developer experience

Composes the shared Button and IconButton primitives for its two actions.
Provide label or an icon for the primary action; icon-only usage also requires accessibleLabel.
menuLabel names both the trailing menu button and its popup.
Both prop bags forward primitive-specific options. SplitButton supplies each part's content and coordinates size, variant, shape, and disabled state.
Each button morphs only its own inner corners on hover, focus-visible, and press. While the menu is open, only the trailing button keeps its expanded shape and selected state layer.
Each action has a unique, non-empty id and visible label; the action model is shared by all frameworks.
open is controlled; defaultOpen initializes uncontrolled use.

Accessibility

The trailing IconButton exposes aria-haspopup="menu", aria-expanded, and aria-controls.
Enter and Space open the menu; Arrow Down and Arrow Up open it at the first and last enabled actions.
The menu supports the shared Menu keyboard model. Escape closes it and restores focus to the menu button.
Both button parts keep a 48px minimum touch target and a visible focus outline.

Known limitations

The primary action is a button callback; use a separate Link for primary navigation.
Nested menu actions are not supported. Use a separate popup composition for submenus.

Props

React props
Name	Type	Required	Default	Description
`label`	`string`	No	`—`	Visible label for the primary action. Provide `icon` for an icon-only action.
`icon`	`Icon`	No	`—`	Optional icon shown before the primary action label.
`accessibleLabel`	`string`	No	`—`	Accessible-name override for the primary action when it has no visible label.
`menuLabel`	`string`	Yes	`—`	Accessible name shared by the trailing menu button and its menu.
`actions`	`readonly SplitButtonAction[]`	Yes	`—`	Related menu actions. Include at least one action with a unique, non-empty `id` and a non-empty `label` for each record.
`variant`	`SplitButtonVariant`	No	`'filled'`	Visual treatment.
`size`	`SplitButtonSize`	No	`'small'`	Visual size. Every size keeps a 48px touch target.
`primaryButtonProps`	`Partial<Omit<ButtonProps, "label" \| "icon" \| "variant" \| "size" \| "disabled" \| "type" \| "iconPosition" \| "shape" \| "shapeFeedback" \| "toggleable" \| "pressed" \| "defaultPressed">>`	No	`—`	Additional Button options; shared SplitButton properties remain authoritative.
`menuButtonProps`	`Partial<Omit<IconButtonProps, "label" \| "icon" \| "variant" \| "size" \| "disabled" \| "shape" \| "shapeFeedback" \| "toggleable" \| "pressed" \| "defaultPressed">>`	No	`—`	Additional IconButton options; shared SplitButton properties remain authoritative.
`disabled`	`boolean`	No	`false`	Disables the primary action, menu trigger, and every menu action.
`open`	`boolean`	No	`—`	Controlled visibility of the related-actions menu.
`defaultOpen`	`boolean`	No	`false`	Initial menu visibility when `open` is uncontrolled.
`className`	`string \| ClassNameComponent<SplitButtonInterface> \| Partial<Record<"splitButton" \| "primaryButton" \| "primaryTouchTarget" \| "primaryStateLayer" \| ... 6 more ... \| "menuSurface", string>>`	No	`—`	Classes or state-aware element classes applied through the shared style contract.
`onPrimaryAction`	`() => void`	No	`—`	Runs the primary action.
`onActionSelect`	`(action: SplitButtonAction, index: number) => void`	No	`—`	Notifies selection before the menu closes.
`onOpenChange`	`(open: boolean) => void`	No	`—`	Notifies an accepted open-state request.