Add this component

npx zentauri-ui add split-button

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

Check Installation for shared peers. This component keeps styling in Tailwind classes and the --zui-* token contract.

Actions

Split button for primary and secondary actions

Split button combines a primary action button with an adjacent menu trigger. Use it when one action should stay immediate while adjacent options such as Save As, Export, Duplicate, Schedule, or Archive remain available from the dropdown.

Split button variants playground

Pick a variant, size, or toggle disabled and loading states to preview the split button live. Toggle Show output / Show code and the snippet updates to match.

Appearance

Size

Trigger on

DisabledLoading

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

default

secondary

destructive

outline

ghost

link

glass

blue

cyan

green

lime

mint

ocean

sapphire

lavender

ruby

red

slate

zinc

stone

royal

electric

forest

sunset

magenta

crimson

aqua

plum

emerald

indigo

purple

pink

rose

sky

teal

yellow

orange

gray

amber

violet

gradient-blue

gradient-green

gradient-red

gradient-yellow

gradient-purple

gradient-teal

gradient-indigo

gradient-pink

gradient-orange

Examples

Split button keeps the primary action immediately available while the trigger opens secondary menu actions with the same appearance and size.

No action selected

Split Button API

Generated from the package prop types and variant definitions.

SplitButton

SplitButtonProps

Variants

Prop	Type	Default
fullWidth	`true`	none

State

Prop	Type	Default
defaultOpen	`boolean \| undefined`	none
onOpenChange	`((open: boolean) => void) \| undefined`	none
open	`boolean \| undefined`	none

Behavior

Prop	Type	Default
appearance	'default' \| 'outline' \| 'ghost' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gradient-orange' \| 'link' \| 'gray' \| 'violet' \| 'glass' \| 'secondary' \| 'destructive' \| 'amber' \| null \| undefined	none
disabled	`boolean \| undefined`	none
items*	`SplitButtonItem[]`	none
label*	`string`	none
loading	`boolean \| undefined`	none
onClick	`MouseEventHandler<HTMLButtonElement> \| undefined`	none
size	`SplitButtonSize \| undefined`	none
startIcon	`ReactNode`	none
triggerLabel	`string \| undefined`	none
triggerOn	`'hover' \| 'click' \| undefined`	none
variant	`SplitButtonVariant \| undefined`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

What it does

Split button renders two adjacent real button controls: the primary side fires onClick, while the trigger side opens a menu of secondary items. Disabled and loading states disable both halves and prevent the dropdown from opening.

Composition and API

Import SplitButton from the split-button entrypoint. Provide label, items, and optional onClick. Items use id, label, icon, disabled, and onSelect. The component also accepts appearance, variant aliases, size, startIcon, fullWidth, open, defaultOpen, and onOpenChange.

Common use cases

Reach for Split button when a default action has nearby alternatives: Save with Save As and Export, Publish with Schedule and Preview, Send with Save draft and Send copy, or Archive with Duplicate and Move.

Accessibility

Both halves are native buttons. The menu trigger exposes aria-haspopup, aria-expanded, and an accessible label. Menu focus movement, Escape handling, Home, End, ArrowUp, and ArrowDown behavior are delegated to the shared Dropdown primitive.

Next.js integration notes

Split button is a client component because it uses interactive dropdown state. Render it in client components or inside interactive islands in App Router pages.

FAQ

Can the menu open state be controlled?

Yes. Pass open and onOpenChange to control the dropdown trigger state from parent state.

Can menu items include icons?

Yes. Add an icon to any item. The item label remains the accessible menu item name.

How do variant aliases map to Button appearances?

The variant prop supports primary, secondary, outline, ghost, danger, and success. These map to the existing Button appearance system, and the appearance prop can be used directly for the full tokenized palette.