ComponentsEnterpriseSplitButton

SplitButton

SplitButton pairs one primary action with a menu of closely related alternatives.

Primary + menu3 variants3 sizesKeyboard menuControlled open

Overview

Use SplitButton when one action is clearly the default and a small menu exposes variations of that same intent.

Publish actions

Live preview

Run the default publish action or choose a closely related alternative.

Ready to publish

PublishButton.tsx
tsx
import { SplitButton } from 'omverse-ui'
 
<SplitButton
leadingIcon="upload"
onClick={publishNow}
items={[
{ id: 'draft', label: 'Save as draft', icon: 'bookmark', onSelect: saveDraft },
{ id: 'schedule', label: 'Schedule publish', icon: 'play', onSelect: schedule },
]}
>
Publish
</SplitButton>

Anatomy

The control joins a default action and menu trigger while the open menu lists closely related alternatives.

☆ Save as draft

▷ Schedule publish

▤ Save as template

12345
  1. 1
    Primary action

    Runs the most likely action immediately.

  2. 2
    Shared boundary

    Communicates that both controls belong to one action family.

  3. 3
    Menu trigger

    Opens the related alternatives without running the default.

  4. 4
    Action menu

    Provides a named menu surface.

  5. 5
    Alternative item

    Runs one closely related action and closes the menu.

When to use

Use when a stable default action accounts for most use while two to five related variations remain useful.

Recommended

  • Preserve a strong default

    Keep publish, save, create, or export immediately available.

  • Group variations

    Offer schedule publish, save draft, or export formats.

  • Support repeat work

    Reduce steps for the action people choose most often.

When not to use

Use separate controls when actions differ in intent, importance, or consequence.

Avoid

  • Do not mix unrelated actions

    Use Toolbar or DropdownMenu for broader command sets.

  • Do not hide destructive action

    Separate irreversible actions from a routine default.

  • Do not use without a clear default

    Use DropdownMenu when every action has equal likelihood.

Variants

Emphasis and size follow the importance of the shared action family.

Filled

High-emphasis primary action.

Outlined

Medium emphasis on neutral surfaces.

Tonal

Lower emphasis within grouped workflows.

Sizes

Small, medium, and large preserve matched controls.

States

Primary and menu controls share availability and progress while the menu tracks its own visibility and focus.

StateTriggerVisual responseInteraction
ClosedAlternatives hiddenJoined primary and triggerEither control available
OpenMenu trigger activatesMenu below groupFirst enabled item focused
Focused itemKeyboard navigationTonal item surfaceEnter selects
LoadingPrimary work activeProgress and loading textBoth controls disabled
DisabledAction family unavailableReduced emphasisNo activation

Behavior

SplitButton owns menu interaction while applications own action execution, confirmation, authorization, and side effects.

Primary execution

Primary action never opens the alternatives menu.

Menu selection

An enabled alternative executes and closes the menu.

Dismissal

Escape and outside pointer interaction close the menu.

Focus return

Selection or Escape returns focus to the trigger.

Accessibility

SplitButton exposes two native buttons and a named menu with standard roving keyboard navigation.

KeyAction
TabMoves between primary action and menu trigger.
EnterSpaceRuns the focused control or menu item.
↓Opens the menu from its trigger or moves to the next item.
↑Moves to the previous menu item.
HomeEndMoves to the first or last item.
EscCloses the menu and returns focus.
  • Give the trigger a label describing the action family.
  • Keep the primary visible label explicit.
  • Use menu semantics only for executable alternatives.
  • Disable both controls while the primary action is loading.
  • Return focus after selection and dismissal.
  • Keep destructive alternatives separated or clearly labeled.

Content guidelines

The primary label and alternatives should share one clear verb or outcome family.

Name the default

Use a verb-first primary label.

ExamplePublish

Qualify alternatives

Explain how the related outcome differs.

ExampleSchedule publish

Keep labels parallel

Use consistent action-object grammar.

ExampleSave as draft, Save as template

Avoid generic trigger text

Use an accessible menu label tied to the action.

ExampleMore publish actions

Examples

Controlled menu visibility and loading support workflows that coordinate overlays and asynchronous action state.

Controlled action family

Live preview

Ready to publish

ControlledPublish.tsx
tsx
<SplitButton items={actions} open={open} onOpenChange={setOpen} loading={isPublishing}>Publish</SplitButton>

Props / API

SplitButton extends div attributes; each alternative defines identity, content, icon, availability, consequence, and execution.

Props

PropTypeDefaultDescription
childrenReactNoderequiredPrimary action label.
onClick() => voidundefinedRuns the primary action.
itemsreadonly SplitButtonItem[]requiredClosely related alternatives.
openbooleanundefinedControlled menu visibility.
defaultOpenbooleanfalseInitial uncontrolled visibility.
onOpenChange(open: boolean) => voidundefinedRuns when menu visibility changes.
onItemSelect(item) => voidundefinedRuns after an enabled alternative is selected.
menuLabelstring'More actions'Accessible label for the menu trigger.
leadingIconIconNameundefinedOptional primary action icon.
disabledbooleanfalseDisables both controls.
loadingbooleanfalseShows primary action progress and disables both controls.
loadingTextReactNode'Working…'Primary label shown while loading.
variant'filled' | 'outlined' | 'tonal''filled'Controls action emphasis.
size'sm' | 'md' | 'lg''md'Controls target height and spacing.