Split button

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

SplitButton renders a Button for the main label (children) and a Menu triggered by a chevron Interactable. Pass sibling menu content with the menuContent prop using SplitButtonItem, SplitButtonSeparator, SplitButtonLabel, and grouped variants (SplitButtonCheckbox, SplitButtonRadio, SplitButtonSwitch) as needed. Optional menuOpen / onMenuOpenChange control the menu; menuSide and menuAlign position the popover.

Props

Name	Type	Default	Description
`children`	`ReactNode`	—	Menu rows: `MenuItem`, `MenuCheckboxItem`, `MenuRadioGroup`, `MenuGroup`, `MenuSeparator` and `MenuSub`. Mark a destructive row with `destructive` on `MenuItem`.
`label`	`LocalizedMessage`	—	Label of the primary action. When it changes the old label fades and blurs out and the new one fades in, and the button's width springs between the two widths. In the action shape this is the label at rest.
`menuLabel`	`LocalizedMessage`	—	Accessible name of the chevron trigger, such as "More save options". Never drawn.
`active`	`boolean`	—	Non-toggle pressed or transient current marker; hosts write the `pressed` state key through `stateAttributes` (`data-pressed`). A toggle host (Button toggle variant) uses `aria-pressed` and styles with `[aria-pressed="true"]` without also writing `data-pressed` for that toggle state (ADR 0001 rule 1). Link "current" within a set uses `aria-current`, not `active`.
`aria-current`	`boolean \| "time" \| "false" \| "true" \| "page" \| "step" \| "location" \| "date"`	—	Whether this item is current within a set.
`aria-describedby`	`string`	—	Id of the element that describes this control.
`aria-description`	`LocalizedMessage`	—	Accessible description when it cannot be referenced by id.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-labelledby`	`string`	—	Id of the element that names this control.
`defaultMenuOpen`	`boolean`	`false`	Initial open state of the menu when uncontrolled.
`disabled`	`boolean`	—	Inert state per host: native `disabled` on a `button`; on Link, ADR 0006 link host (no `href`, `aria-disabled="true"`, `tabIndex={0}`). Never `tabIndex={-1}`.
`groupLabel`	`LocalizedMessage`	—	Accessible name of the pair, which is a `role="group"`. Defaults to the primary button's own name, so the group is named by the action it wraps.
`id`	`string`	—	Element `id` for ARIA relationships.
`intent`	`ButtonIntent`	—	Visual intent. Defaults to {@link ButtonIntent.Neutral}.
`leading`	`ReactNode`	—	Content before the label.
`menuAlign`	`Align`	`"end"`	Alignment of the menu along that edge, against the whole pair.
`menuOpen`	`boolean`	—	Controlled open state of the menu. Pair with `onMenuOpenChange`.
`menuSide`	`Side`	`"block-end"`	Preferred edge of the pair the menu opens against. Flips to the opposite edge when there is no room.
`onAction`	`(() => unknown)`	—	Runs on click while the button is idle or showing success. The button is pending until the returned promise settles: a resolved promise shows the success state, a rejected one (or a synchronous throw) returns to idle and calls {@link ActionButtonOwnProps.onActionError}. A synchronous return counts as resolved. Needs the action shape. @returns A promise to wait for, or nothing
`onActionError`	`((error: unknown) => void)`	—	Called with whatever `onAction` rejected or threw. The button has already returned to idle. The button shows no error state of its own, so report the failure here (a toast, a field error). Needs the action shape. @param error - The rejection reason
`onMenuOpenChange`	`MenuOpenChangeHandler`	—	Called when the menu opens or closes from user or platform input.
`pendingLabel`	`LocalizedMessage`	—	Label while `onAction` is pending. Announced to assistive technology when it appears. Needs the action shape.
`preventFocusOnPress`	`boolean`	`false`	When true, `mousedown` does not move focus to the button (field adornments).
`ref`	`Ref<HTMLButtonElement>`	—	Ref to the rendered `button`.
`size`	`ButtonSize`	—	Control size. Defaults to {@link ButtonSize.Large}.
`successLabel`	`LocalizedMessage`	—	Label while the success state shows. Announced to assistive technology when it appears. Needs the action shape.
`tooltip`	`LocalizedMessage`	—	Short text shown in a Tooltip while the pointer hovers the button or a navigation key focuses it. Button composes Tooltip's trigger, content and root, so it behaves like `Tooltip > TooltipTrigger > Button` and also works while `disabled` (pointer only) and on toggle buttons. A labelled button points `aria-describedby` at the tooltip. An icon-only button does not: `label` already names it, so the tooltip is visual only and never read twice. Adding or removing the prop after mount remounts the button.
`type`	`"button" \| "submit" \| "reset"`	—	Native button type. Defaults to `button`.
`variant`	`ButtonVariant`	—	Surface variant. Defaults to {@link ButtonVariant.Soft}.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Primary

Secondary

With lead icon

Sizes

Disabled

All variants

Split button / Usage

Split button / Accessibility

On this page

Split button

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Props

Name	Type	Default	Description
`children`	`ReactNode`	—	Menu rows: `MenuItem`, `MenuCheckboxItem`, `MenuRadioGroup`, `MenuGroup`, `MenuSeparator` and `MenuSub`. Mark a destructive row with `destructive` on `MenuItem`.
`label`	`LocalizedMessage`	—	Label of the primary action. When it changes the old label fades and blurs out and the new one fades in, and the button's width springs between the two widths. In the action shape this is the label at rest.
`menuLabel`	`LocalizedMessage`	—	Accessible name of the chevron trigger, such as "More save options". Never drawn.
`active`	`boolean`	—	Non-toggle pressed or transient current marker; hosts write the `pressed` state key through `stateAttributes` (`data-pressed`). A toggle host (Button toggle variant) uses `aria-pressed` and styles with `[aria-pressed="true"]` without also writing `data-pressed` for that toggle state (ADR 0001 rule 1). Link "current" within a set uses `aria-current`, not `active`.
`aria-current`	`boolean \| "time" \| "false" \| "true" \| "page" \| "step" \| "location" \| "date"`	—	Whether this item is current within a set.
`aria-describedby`	`string`	—	Id of the element that describes this control.
`aria-description`	`LocalizedMessage`	—	Accessible description when it cannot be referenced by id.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-labelledby`	`string`	—	Id of the element that names this control.
`defaultMenuOpen`	`boolean`	`false`	Initial open state of the menu when uncontrolled.
`disabled`	`boolean`	—	Inert state per host: native `disabled` on a `button`; on Link, ADR 0006 link host (no `href`, `aria-disabled="true"`, `tabIndex={0}`). Never `tabIndex={-1}`.
`groupLabel`	`LocalizedMessage`	—	Accessible name of the pair, which is a `role="group"`. Defaults to the primary button's own name, so the group is named by the action it wraps.
`id`	`string`	—	Element `id` for ARIA relationships.
`intent`	`ButtonIntent`	—	Visual intent. Defaults to {@link ButtonIntent.Neutral}.
`leading`	`ReactNode`	—	Content before the label.
`menuAlign`	`Align`	`"end"`	Alignment of the menu along that edge, against the whole pair.
`menuOpen`	`boolean`	—	Controlled open state of the menu. Pair with `onMenuOpenChange`.
`menuSide`	`Side`	`"block-end"`	Preferred edge of the pair the menu opens against. Flips to the opposite edge when there is no room.
`onAction`	`(() => unknown)`	—	Runs on click while the button is idle or showing success. The button is pending until the returned promise settles: a resolved promise shows the success state, a rejected one (or a synchronous throw) returns to idle and calls {@link ActionButtonOwnProps.onActionError}. A synchronous return counts as resolved. Needs the action shape. @returns A promise to wait for, or nothing
`onActionError`	`((error: unknown) => void)`	—	Called with whatever `onAction` rejected or threw. The button has already returned to idle. The button shows no error state of its own, so report the failure here (a toast, a field error). Needs the action shape. @param error - The rejection reason
`onMenuOpenChange`	`MenuOpenChangeHandler`	—	Called when the menu opens or closes from user or platform input.
`pendingLabel`	`LocalizedMessage`	—	Label while `onAction` is pending. Announced to assistive technology when it appears. Needs the action shape.
`preventFocusOnPress`	`boolean`	`false`	When true, `mousedown` does not move focus to the button (field adornments).
`ref`	`Ref<HTMLButtonElement>`	—	Ref to the rendered `button`.
`size`	`ButtonSize`	—	Control size. Defaults to {@link ButtonSize.Large}.
`successLabel`	`LocalizedMessage`	—	Label while the success state shows. Announced to assistive technology when it appears. Needs the action shape.
`tooltip`	`LocalizedMessage`	—	Short text shown in a Tooltip while the pointer hovers the button or a navigation key focuses it. Button composes Tooltip's trigger, content and root, so it behaves like `Tooltip > TooltipTrigger > Button` and also works while `disabled` (pointer only) and on toggle buttons. A labelled button points `aria-describedby` at the tooltip. An icon-only button does not: `label` already names it, so the tooltip is visual only and never read twice. Adding or removing the prop after mount remounts the button.
`type`	`"button" \| "submit" \| "reset"`	—	Native button type. Defaults to `button`.
`variant`	`ButtonVariant`	—	Surface variant. Defaults to {@link ButtonVariant.Soft}.