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-menuAdds 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.
The demo in the preview, 264 lines
"use client"
import * as React from "react"
import { Download, GitMerge, Undo2 } from "lucide-react"
import { Button } from "@/components/ui/button"
import {
SplitButtonMenu,
type SplitButtonAction,
} from "@/components/hazine/split-button-menu"
const BRANCH = "retry-webhooks"
const BRANCH_COMMITS = 3
const CHECKS = 14
const MERGE: SplitButtonAction = { id: "merge", label: "Merge pull request" }
const MERGE_ALTERNATIVES: SplitButtonAction[] = [
{
id: "squash",
label: "Squash and merge",
description: `Combines the ${BRANCH_COMMITS} commits into one on main.`,
},
{
id: "rebase",
label: "Rebase and merge",
description: "Not available. This repository requires signed commits.",
disabled: true,
},
{
id: "close",
label: "Close without merging",
description: `Leaves main untouched and keeps ${BRANCH}.`,
tone: "destructive",
},
]
function commits(count: number) {
return count === 1 ? "1 commit" : `${count} commits`
}
// What each action does to main, so the sentence always matches the branch.
function outcomeOf(id: string) {
if (id === "squash") {
return {
lead: "Squashed and merged.",
detail: `${commits(1)} added to main, combining ${BRANCH_COMMITS} from ${BRANCH}.`,
undoLabel: "Revert merge",
}
}
if (id === "close") {
return {
lead: "Closed without merging.",
detail: `${commits(0)} added to main. ${BRANCH} still holds ${BRANCH_COMMITS}.`,
undoLabel: "Reopen pull request",
}
}
return {
lead: "Merged with a merge commit.",
detail: `${commits(BRANCH_COMMITS + 1)} added to main: ${BRANCH_COMMITS} from ${BRANCH} + 1 merge commit.`,
undoLabel: "Revert merge",
}
}
export default function SplitButtonMenuDemo() {
const [ranId, setRanId] = React.useState<string | null>(null)
const controls = React.useRef<HTMLDivElement>(null)
const interacted = React.useRef(false)
const outcome = ranId === null ? null : outcomeOf(ranId)
// The split button and the undo button replace each other, so focus follows
// to whichever one is now on screen.
React.useEffect(() => {
if (!interacted.current) return
controls.current?.querySelector("button")?.focus()
}, [ranId])
function settle(next: string | null) {
interacted.current = true
setRanId(next)
}
return (
<div className="flex flex-col items-start gap-3">
<p role="status" className="text-sm text-muted-foreground">
<span className="font-medium text-foreground tabular-nums">
{outcome
? outcome.lead
: `${commits(BRANCH_COMMITS)} ready to merge into main.`}
</span>{" "}
<span className="tabular-nums">
{outcome
? outcome.detail
: `${CHECKS} of ${CHECKS} checks passed on ${BRANCH}.`}
</span>
</p>
<div ref={controls} className="flex max-w-full">
{outcome ? (
<Button
type="button"
variant="outline"
onClick={() => settle(null)}
>
<Undo2 aria-hidden="true" />
{outcome.undoLabel}
</Button>
) : (
<SplitButtonMenu
aria-label="Merge pull request 482"
primaryAction={MERGE}
actions={MERGE_ALTERNATIVES}
menuLabel="More merge options"
icon={<GitMerge aria-hidden="true" />}
onActionRun={(action) => settle(action.id)}
/>
)}
</div>
</div>
)
}
function LoadingScenario() {
return (
<div className="flex flex-col items-start gap-3">
<p className="text-sm text-muted-foreground">
<span className="font-medium text-foreground tabular-nums">
Merging {commits(BRANCH_COMMITS)} into main.
</span>{" "}
This usually takes a few seconds.
</p>
<SplitButtonMenu
aria-label="Merge pull request 482"
primaryAction={MERGE}
actions={MERGE_ALTERNATIVES}
menuLabel="More merge options"
icon={<GitMerge aria-hidden="true" />}
loading
loadingLabel="Merging"
/>
</div>
)
}
function DisabledScenario() {
const failed = 1
return (
<div className="flex flex-col items-start gap-3">
<p className="text-sm text-muted-foreground">
<span className="font-medium text-foreground">
Merging is blocked.
</span>{" "}
<span className="tabular-nums">
{CHECKS - failed} of {CHECKS} checks passed, {failed} failed:
integration tests on Node 22.
</span>
</p>
<SplitButtonMenu
aria-label="Merge pull request 482"
primaryAction={MERGE}
actions={MERGE_ALTERNATIVES}
menuLabel="More merge options"
icon={<GitMerge aria-hidden="true" />}
disabled
/>
</div>
)
}
const ROWS = 1284
const EXPORT_FORMATS: SplitButtonAction[] = [
{ id: "xlsx", label: "Export as Excel workbook" },
{ id: "pdf", label: "Export as PDF summary" },
{ id: "json", label: "Export as JSON" },
]
function OutlineCompactScenario() {
const [format, setFormat] = React.useState<string | null>(null)
const rows = new Intl.NumberFormat("en-US").format(ROWS)
return (
<div className="flex flex-col items-start gap-3">
<SplitButtonMenu
aria-label="Export deliveries"
variant="outline"
density="compact"
primaryAction={{ id: "csv", label: "Export CSV" }}
actions={EXPORT_FORMATS}
menuLabel="More export formats"
icon={<Download aria-hidden="true" />}
onActionRun={(action) => setFormat(action.id.toUpperCase())}
/>
<p role="status" className="text-xs text-muted-foreground tabular-nums">
{format
? `Exported ${rows} deliveries as ${format}.`
: `${rows} deliveries match the current filters.`}
</p>
</div>
)
}
const DEPLOY_TARGETS: SplitButtonAction[] = [
"Frankfurt",
"Amsterdam",
"Dublin",
"Stockholm",
"Warsaw",
"Virginia",
"Oregon",
"Singapore",
"Sydney",
].map((city, index) => ({
id: city.toLowerCase(),
label: `Deploy to the ${city} staging cluster only`,
description:
index % 3 === 0
? `Rolls out to ${index + 2} nodes one at a time and waits for health checks between each of them.`
: undefined,
}))
function OverflowScenario() {
return (
<div className="flex w-56 max-w-full flex-col gap-3">
<p className="text-sm text-muted-foreground">
<span className="font-medium text-foreground tabular-nums">
{DEPLOY_TARGETS.length} staging clusters.
</span>{" "}
Deploy to all of them, or pick one from the menu.
</p>
<SplitButtonMenu
aria-label="Deploy release 2026.11.2"
className="flex"
primaryAction={{
id: "all",
label: "Deploy release 2026.11.2 to every staging cluster",
}}
actions={DEPLOY_TARGETS}
menuLabel="More deploy targets"
/>
</div>
)
}
export const scenarios = {
loading: LoadingScenario,
disabled: DisabledScenario,
overflow: OverflowScenario,
"outline-compact": OutlineCompactScenario,
"menu-open": () => (
<SplitButtonMenu
aria-label="Merge pull request 482"
primaryAction={MERGE}
actions={MERGE_ALTERNATIVES}
menuLabel="More merge options"
icon={<GitMerge aria-hidden="true" />}
defaultOpen
/>
),
empty: () => (
<SplitButtonMenu
primaryAction={MERGE}
actions={[]}
icon={<GitMerge aria-hidden="true" />}
/>
),
}
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 Key Effect Tab Moves from the main button to the caret, then out of the group Enter or Space on the main button Runs the default action Enter, Space or Arrow Down on the caret Opens the menu and focuses the first item Arrow Up, Arrow Down Moves between menu items Home, End Moves to the first or last menu item Any letter Moves to the next item whose label starts with it Enter or Space on a menu item Runs the action, closes the menu and returns focus to the caret. An unavailable item does nothing and the menu stays open Escape Closes 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.