Skip to content
Hazine

Split Button with Menu

A default action joined to a caret button that opens a menu of related actions, each run as soon as it is chosen. Use it when one action is the usual choice and a few alternatives must stay one step away.

How it differs. Two focus stops in one group: the main half runs the default action, the caret is a named menu button whose items are alternative actions that run on choice, in a menu as wide as the group.

Install

pnpm dlx shadcn@latest add @hazine/split-button-menu

Adds 1 file, 3 shadcn primitives (button, button-group, dropdown-menu), 1 Hazine item (@hazine/use-controllable-state), and 1 package (lucide-react).

First time? Add the registry to components.json
{
  "registries": {
    "@hazine": "https://api.hazine.dev/r/{name}.json"
  }
}

Needed once per project. Items resolve each other through the @hazine namespace.

Props13

primaryAction
SplitButtonAction = DEFAULT_PRIMARY_ACTION
The default action, run by the main button.
actions
SplitButtonAction[] = DEFAULT_ACTIONS
Related actions listed in the menu. With none, the caret is not rendered.
onActionRun
(action: SplitButtonAction) => void
Called by the main button and by a chosen menu item.
menuLabel
string = "More merge options"
Accessible name of the caret button and of the menu it opens.
icon
React.ReactNode
Shown before the main label.
variant
"default" | "secondary" | "outline" = "default"
density
"compact" | "default" | "comfortable" = "default"
disabled
boolean = false
loading
boolean = false
Both halves stop responding and keep focus while the action runs.
loadingLabel
string = "Working"
Progressive verb that replaces the main label while loading.
open
boolean
defaultOpen
boolean = false
onOpenChange
(open: boolean) => void

Also accepts every prop of Omit<React.ComponentProps<"div">, "children">.

Accessibility

Keyboard
Keyboard support for Split Button with Menu
KeyEffect
TabMoves from the main button to the caret, then out of the group
Enter or Space on the main buttonRuns the default action
Enter, Space or Arrow Down on the caretOpens the menu and focuses the first item
Arrow Up, Arrow DownMoves between menu items
Home, EndMoves to the first or last menu item
Any letterMoves to the next item whose label starts with it
Enter or Space on a menu itemRuns the action, closes the menu and returns focus to the caret. An unavailable item does nothing and the menu stays open
EscapeCloses the menu and returns focus to the caret
Screen reader

A native button beside an APG menu button inside one group. The caret has its own name, which also names the menu. Item descriptions are tied with aria-describedby, and an unavailable item stays focusable so its reason is read.

  • Announces: {loadingLabel}
Reduced motion
The caret does not rotate and the loading icon does not spin. The menu opens with the host's own dropdown styles.
Checked
Not checked yet. Automated results appear here once CI has run.

Dependencies5

  • button
  • button-group
  • dropdown-menu
  • @hazine/use-controllable-state
  • lucide-react

Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.

Tokens shipped0

None. The item is styled by the tokens your theme already has.

More in Buttons and Actions