{
"name": "SplitButton",
"source": "src/components/SplitButton.tsx",
"propsType": "SplitButtonProps",
"description": "SplitButton — one main action, with a menu of variations on it beside:\nSave, and Save as draft; Run now, and Run with a test input.\n\nTWO BUTTONS, TWO TAB STOPS\n\nThe halves are separate Buttons in a `group`, not one control with a hot\nzone. Each is announced and reached on its own: the main one by its label,\nthe menu one as \"More options, Save\" — its own name, then the action it\nbelongs to, so a page with three split buttons has three distinct menu\nbuttons, not three called \"More options\". The menu one is a MenuTrigger,\nso it announces `aria-haspopup` and `aria-expanded`, and ↓ opens it.\n\nNOT A MENU WITH A DEFAULT. Pressing the main half does the action, always\nthe same one; it never becomes whichever alternative was chosen last. A\nbutton whose meaning changes with history cannot be pressed with\nconfidence.",
"import": "import { SplitButton } from 'ionbase-ui';",
"status": "stable",
"summary": "One main action with a menu of variations on it beside — Save, and Save as draft; Create agent, and Create and start. Two buttons, two tab stops, one shape.",
"useWhen": [
"one action is the common case and a few variations of the same action are occasionally needed — save as draft, create and start, export as CSV",
"the variations would crowd the row as buttons of their own, and hiding the main action behind a menu would cost the common case a click"
],
"useInstead": [
{
"when": "the choices are different actions, not variations of one",
"use": "MenuTrigger",
"why": "a split button promises its menu is \"this, but slightly otherwise\"; unrelated actions under it hide what they are behind the wrong label"
},
{
"when": "there are two actions of equal standing",
"use": "ButtonGroup",
"why": "two visible buttons are faster than one and a menu, and neither is hidden"
},
{
"when": "the choice is a setting that changes what the main action does — the export format for every export",
"use": "Select beside a Button",
"why": "a split button's main half always does the same thing; a remembered choice belongs in a control that shows it"
}
],
"composition": {
"order": [
"SplitButton",
"MenuItem"
],
"note": "`label` and `onPress` are the main action; the children are MenuItems for the variations, each with a `key` that `onAction` receives.",
"example": " key === 'draft' && saveDraft()}>"
},
"variants": {
"variant": {
"primary-brand": {
"use": "the default — the single most important action in a view; one per view, as for Button"
},
"primary-neutral": {
"use": "a primary action that should not carry brand colour"
},
"secondary": {
"use": "an action beside the primary, such as Export among a table's actions"
}
},
"size": {
"sm": {
"use": "toolbars and table headers"
},
"md": {
"use": "the default"
},
"lg": {
"use": "a page's single call to action"
},
"xl": {
"use": "rarely — hero actions"
}
}
},
"slots": {
"children": {
"accepts": "MenuItem, MenuSection",
"note": "the variations; each names the whole action — \"Save as draft\", not \"As draft\""
},
"startIcon": {
"accepts": "Icon",
"note": "on the main half only"
}
},
"a11y": {
"requires": [
"`label` — the main half's name and the group's name",
"`menuLabel` translated; the default is \"More options\""
],
"guarantees": [
"a `group` named by `label`, holding two Buttons that are two tab stops, the main one first",
"the menu half is named for itself and the action — \"More options, Save\" — so several split buttons on a page have distinct menu buttons",
"the menu half is a MenuTrigger: `aria-haspopup`, `aria-expanded`, ↓ opens on the first item, choosing closes the menu and returns focus to it",
"the main half always does the same action; choosing a variation never changes it",
"`isDisabled` disables both halves; `isMenuDisabled` only the menu, leaving the action; `disabledKeys` disables single variations",
"`type=\"submit\"` makes the main half submit its form; the menu half never does",
"drawn as one button: one shared border at the seam, square inner corners, a square menu half; the focused half is lifted so its ring is not cut",
"in a stacked ButtonGroup it takes the full width, the main half growing"
],
"notes": [
"a variation that is dangerous — \"Delete permanently\" beside \"Archive\" — should not share a button with a safe action; it needs its own confirmation",
"the menu's actions are reached through `onAction`, not through a submit: a variation that has to submit the form calls the same handler with its option, as the demo's wizard does"
]
},
"antiPatterns": [
{
"dont": "a main half that becomes whichever variation was chosen last",
"do": "the same main action every time",
"why": "a button whose meaning changes with history cannot be pressed with confidence, and a screen reader is not told it changed"
},
{
"dont": "a Button and an icon-only MenuTrigger placed side by side by hand",
"do": "",
"why": "the hand-built menu button is usually named only \"More\", has its own gap and radius, and is not grouped with the action it belongs to"
},
{
"dont": "…edit, delete, share…",
"do": " with a Button named for what it opens",
"why": "\"Actions\" is not an action; pressing the main half has to do something"
},
{
"dont": "collecting MenuItems into a `React.ReactElement[]` and passing the array as the children",
"why": "the children are typed `CollectionChildren`: one collection element, an array of them, or a render function. `ReactElement` defaults its props to `unknown`, which is not an item's props, so the array fails to compile. Write the variations out, with `cond ? : null` for one that comes and goes"
}
],
"stylesheet": "src/styles/split-button.css",
"tokens": [
"--border-width-default",
"--ion-button-size"
],
"props": {
"label": {
"type": "string",
"required": true,
"origin": "own",
"description": "The main action's label — \"Save\", \"Run now\"."
},
"onPress": {
"type": "((e: import(\"/Users/raza/Documents/Apps/ionbase-design-system/node_modules/.pnpm/@react-types+shared@3.36.0_react@19.2.8/node_modules/@react-types/shared/src/events\").PressEvent) => void) | undefined",
"required": false,
"origin": "own",
"description": "The main action."
},
"type": {
"type": "\"button\" | \"submit\" | undefined",
"required": false,
"origin": "own",
"description": "`type=\"submit\"` makes the main action submit its form.",
"values": [
"button",
"submit"
]
},
"children": {
"type": "CollectionChildren