Split Button

Material Design 3 split button combining a primary action with a dropdown menu for related actions. Provides quick access to a default action while offering additional options through the menu. Not intended when all actions have equal priority; use separate buttons in those scenarios.

Basic Usage

Combines a primary action button with a dropdown menu trigger so the most common action stays one click away while alternatives remain discoverable.

Save Save As...

Save All

Save a Copy

<ds-split-button>
  Save
  <ds-menu-item slot="menu" value="save-as">Save As...</ds-menu-item>
  <ds-menu-item slot="menu" value="save-all">Save All</ds-menu-item>
  <ds-menu-item slot="menu" value="save-copy">Save a Copy</ds-menu-item>
</ds-split-button>

Variants

Split buttons support all standard button variants

Filled

High emphasis for primary actions

Send Email Send and Archive

Schedule Send

Send to Multiple

<ds-split-button variant="filled">Send Email</ds-split-button>

Filled Tonal

Medium emphasis with tonal background

Export Export as PDF

Export as CSV

Export as JSON

<ds-split-button variant="filled-tonal">Export</ds-split-button>

Outlined

Medium emphasis with border

Share Share Link

Share via Email

Copy to Clipboard

<ds-split-button variant="outlined">Share</ds-split-button>

Elevated

Medium emphasis with shadow

Download Download High Quality

Download Original

Download All

<ds-split-button variant="elevated">Download</ds-split-button>

Text

Low emphasis for less prominent actions

More View Details

Edit

Delete

<ds-split-button variant="text">More</ds-split-button>

Menu Position

Control where the menu appears relative to the button

Only one menu can be open at a time in this demo.

<ds-split-button position="bottom-start">Bottom Start</ds-split-button>
<ds-split-button position="bottom-end">Bottom End</ds-split-button>
<ds-split-button position="top-start">Top Start</ds-split-button>
<ds-split-button position="top-end">Top End</ds-split-button>

States

Disabled

Disabled state for both buttons

Disabled Option 1

Option 2

<ds-split-button disabled>Disabled</ds-split-button>

Interactive Example

Click the primary button or menu items to see events

Primary Action Secondary Action 1

Secondary Action 2

Secondary Action 3

Click buttons to see events

const splitBtn = document.querySelector('ds-split-button');

splitBtn.addEventListener('ds-split-button:click', (e) => {
  console.log('Primary action clicked');
});

splitBtn.addEventListener('ds-split-button:menu-select', (e) => {
  console.log('Menu item selected:', e.detail);
});

API

Attributes

Attribute	Type	Default	Description
`variant`	string	'filled'	Button style: 'filled' \| 'filled-tonal' \| 'outlined' \| 'elevated' \| 'text'
`disabled`	boolean	false	Disables both buttons
`position`	string	'bottom-end'	Menu position: 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'

Slots

Slot	Description
(default)	Primary button content
`menu`	Menu items (use ds-menu-item elements)

Events

Event	Detail	Description
`ds-split-button:click`	`{ originalEvent }`	Fired when primary button is clicked
`ds-split-button:menu-select`	`{ item, value, label }`	Fired when menu item is selected

Methods

Method	Parameters	Description
`openMenu()`	none	Opens the dropdown menu
`closeMenu()`	none	Closes the dropdown menu

CSS Parts

Part	Description
`primary-button`	The primary action button
`menu-button`	The dropdown trigger button
`menu`	The dropdown menu container

CSS Custom Properties

Property	Description
`None`	No component-specific custom properties

Accessibility

Keyboard Interaction

Key	Context	Expected Result
`Tab`	Split button present	Moves focus between primary and menu trigger buttons
`Enter` / `Space`	Focus on primary or menu trigger	Activates primary action or opens menu
`Escape`	Menu open	Closes menu and returns focus to trigger

Semantics

Uses aria-haspopup and aria-expanded on the menu trigger.
Dropdown surface follows role="menu" semantics.
Focus is managed between primary and menu actions with clear visual distinction.

Usage Guidelines

When to use: Use when a default action is most common and a small set of related alternatives is needed, such as Save with Save As.
When not to use: Avoid when all actions are equally important or unrelated, and avoid for navigation use cases.
Composition: Keep the primary action clear, limit menu items to 3-7 options, and group related items with dividers when needed.
Common mistakes: Ambiguous primary labels and oversized menus reduce clarity. Prefer concise outcome-oriented action names.