Split Button

Splits an action into two parts — typically a primary action and a secondary action that opens a menu or performs an alternative action.

Save

Overview

Split buttons communicate multiple related actions that users can take while providing a clear primary action alongside alternative options. They consist of a main button for the suggested action and a dropdown arrow that reveals secondary related actions, allowing users to access variations of the primary action without cluttering the interface.

Split buttons are particularly effective when space is limited and multiple related actions need to be accessible through a single interface element.

Usage

forge-split-button groups two or more slotted forge-button children into a single visual unit, propagating variant, theme, disabled, dense, and pill to every button so they render consistently. Pair a primary action with a forge-menu trigger for a classic split button, or slot several buttons directly for a segmented group of equally-weighted actions. For actions that aren’t related to one another, use individual buttons or icon buttons instead.

Rules

Keep every button in a split button related to the same task.

Limit related actions to three, so the group stays easy to scan.

Use the same sentence-case, actionable labels as standalone buttons.

Reserve filled for the one primary action per view, same as individual buttons.

Don't

Don't group unrelated actions into one split button — use individual buttons instead.

Don't use more than one filled split button per page or dialog.

Don't use success or warning themes — use primary.

Slot a primary forge-button alongside a forge-menu whose trigger button carries popover-icon to open a dropdown of related, secondary actions.

A primary action paired with a menu of related actions.

<forge-split-button variant="raised" theme="primary">
  <forge-button style="min-width: 100px;" variant="raised">
    Send
  </forge-button>
  <forge-menu>
    <forge-button aria-label="Show menu" popover-icon variant="raised" aria-atomic aria-live="assertive" aria-haspopup>
    </forge-button>
  </forge-menu>
</forge-split-button>

Multiple actions

Slot several forge-button children directly, without a menu, for a segmented group of equally-weighted actions.

Three related buttons rendered as one segmented group.

<forge-split-button>
  <forge-button variant="outlined">
    Button one
  </forge-button>
  <forge-button variant="outlined">
    Button two
  </forge-button>
  <forge-button variant="outlined">
    Button three
  </forge-button>
</forge-split-button>

Dense and pill

Set dense and pill to shape the group into a compact, rounded control.

A dense, pill-shaped split button.

<forge-split-button dense pill>
  <forge-button variant="outlined">
    Button one
  </forge-button>
  <forge-button variant="outlined">
    Button two
  </forge-button>
</forge-split-button>

Split buttons are used for splitting an action into two parts, typically a primary action and a secondary action that opens a menu or performs an alternative action. Split buttons expect child Forge buttons as their content.

import "@tylertech/forge/split-button";

Properties

Property	Attribute	Type	Default	Description
`variant`	`variant`	`SplitButtonVariant`	`"text"`	The variant of the buttons. Valid values are `text`, `outlined`, `tonal`, `filled`, and `raised`.
`theme`	`theme`	`ButtonTheme`	`"primary"`	The theme of the buttons. Valid values are `primary`, `secondary`, `tertiary`, `success`, `error`, `warning`, `info`.
`disabled`	`disabled`	`boolean`	`false`	Whether or not the buttons are disabled.
`dense`	`dense`	`boolean`	`false`	Whether or not the buttons are dense.
`pill`	`pill`	`boolean`	`false`	Whether or not the buttons are pill-shaped.

Slots

Name	Description
`(default)`	This is a default/unnamed slot.

CSS Custom Properties

Name	Description
`--forge-split-button-min-width`	The minimum width of the slotted buttons.
`--forge-split-button-gap`	The gap between the slotted buttons.
`--forge-split-button-focus-indicator-offset`	The offset of the focus indicator around the buttons.
`--forge-split-button-focus-indicator-divider-offset`	The offset of the focus indicator divider when using outlined buttons.

Accessibility documentation coming soon.

Overview

Usage

Rules

With a menu

Multiple actions

Dense and pill