Split Button
A main action with a second half that opens a menu of related actions, like Save with Save as draft. Each half takes its own focus, and in Arabic the menu half moves to the left.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add split-buttonAlso works with shadcn:
npx shadcn@latest add @ritla/split-buttonDependencies it brings
@base-ui/react@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { SplitButton, SplitButtonItem } from "@/components/ui/split-button";<SplitButton onClick={save} menuLabel="More save options" menu={ <> <SplitButtonItem onClick={saveDraft}>Save as draft</SplitButtonItem> <SplitButtonItem onClick={publish}>Save and publish</SplitButtonItem> </> }> Save</SplitButton>Examples
Styles
Button's filled, tonal, outline and ghost styles, with both halves always in the same one. There's no inverted-ghost and no danger version: a destructive action doesn't hide in a menu.
Sizes
Each size is as tall as the Button of the same size, and the menu half is a square. The tap target stays at least 48px at sm and xs.
API reference
SplitButton
Other Base UI Button props (onClick, type…) go to the main action half.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Label: the main action's text. |
menuLabel | string | None | Required. The menu half's name for screen readers (“More save options”). |
menu | ReactNode | None | SplitButtonItems for the related actions. |
variant | "filled" | "tonal" | "outline" | "ghost" | "filled" | Figma's Style. |
size | "lg" | "md" | "sm" | "xs" | "lg" | Figma's Size: 56, 48, 40 and 32px. |
iconLeading | IconComponent | None | Icon leading: an icon before the label. |
trailingIcon | IconComponent | CaretDownIcon | Trailing btn icon. It never mirrors. |
disabled | boolean | false | State = Disabled on both halves. |
className | string | None | Classes for the outer group. |
SplitButtonItem
A Base UI Menu item; takes onClick and disabled. The menu look is provisional until Figma's menu page is ready.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | The action's text. |
onClick | (event) => void | None | Called on selection; the menu then closes. |
disabled | boolean | false | Disables the item and keeps it visible. |
Anatomy
The parts of a split button and where each one lives in Figma and in code.
- 1. Group
role="group"Two halves with aspace-2gap, laid out inline. In Outline the halves share one border, with no gap. - 2. Leading button
children, iconLeadingThe label and an optional leading icon, corners at the inline start. Its own focus stop; other Button props go here. - 3. Trailing button
trailingIconA square menu half with the CaretDown swap: the menu trigger, witharia-haspopupandaria-expanded. Never mirrors. - 4. Menu label (not drawn)
menuLabelA hidden text property, required: the accessible name of the menu half. - 5. Menu
menuRitla UI menu items 12px under the button, at its inline start;role="menu". - 6. Touch target
size/touch-targetsmandxskeep a 48px hit area on each half, without taking layout space.
Usage guidelines
A split button is one usual action with a few close variations in a menu. When to use it, how to name its halves, and the checks before handoff.
1. One usual action, a few close variations
The main half runs what people do most; the menu holds variations of the same action.
Saving a document
Save, with its variations in the menu.
Do
- Put the most likely action on the main part and the alternatives in the menu.
- Keep the menu to five items or fewer.
Don't
- Use a split button when all actions are equal; use a Button group.
- Change the main action based on the last pick without telling the person.
3. Keep the label short
The label is the main action; the details belong in the menu.
An export bar
Exporting a report.
4. One filled per view
A filled split button is the main action of its view, like a filled Button.
An editor footer
Cancel and Save.
outline Cancel, filled SaveThe main action stands out.filledTwo equal weights compete.5. Destructive actions do not hide in a menu
There is no danger version of the split button. Put a destructive action on its own labeled Button with danger, where people can see it before they press.
Don't
- Hide a destructive action in the split menu without a confirm step.
6. Trade action is not a split button
Both halves of Trade action are primary actions, so it is not a split button. Buy stays on the inline start, and the colours never swap.
7. Arabic and RTL
In Arabic frames use RTL (عربي) = Yes, so the menu half sits on the left. In code there is no prop for it: the direction does it.
An Arabic editor
Save in Arabic.
RTL = YesThe label reads first and the menu half closes the line on the left.RTL = No with Arabic textThe caret lands before the label and the order reads backwards.Before handoff
LabelandMenu labelare filled in the page language.- Menu items are variations of the main action.
- One
filledper view. - Arabic frames use
RTL = Yes. - No destructive action inside the menu.
Tokens & specs
Every value on Split Button is a variable or a text style, the same ones as Button on both halves. These are the ones bound on the component, by size and by style.
Sizes
Height, inline padding and corner radius of each half; the two halves sit space-2 apart (in Outline they share one border-width/thicker line instead). At md, sm and xs the radius runs one step above Button's; at lg it matches. Every size keeps a 48px touch target.
| Size | Height, padding, radius | Label and icons |
|---|---|---|
lg | 56 · space-24 · radius/10 | body-16/Semibold · 24 |
md | 48 · space-24 · radius/10 | body-16/Semibold · 20 |
sm | 40 · space-16 · radius/8 | body-16/Semibold · 20 |
xs | 32 · space-12 · radius/6 | body-14/Semibold · 20 |
Colors
Fill, border and label colour per style in the Enabled state, the same variables as Button, on both halves. Light and dark come from the 1. Colors mode.
| Style | Fill and border | Label and icons |
|---|---|---|
filled | background/brand/solid | text/brand/on-brand |
tonal | background/brand/faint | text/brand/subtle |
outline | background/surface/lowest · border/gray/soft | text/gray/subtle |
ghost | alpha/tint-12 | text/gray/subtle |
Focus
Focused (main) and Focused (menu) draw the Focus/focus-ring effect style around one half. In code it is automatic on :focus-visible.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | Moves from the main action to the menu half; each half shows its own ring. |
| EnterSpace | Runs the main action, or opens the menu from the menu half. |
| ArrowDownArrowUp | Opens the menu and moves between its items. |
| Escape | Closes the menu and returns focus to the menu half. |
ARIA
- Two native buttons in a
role="group"; the menu half carriesaria-haspopup="menu"andaria-expanded. menuLabelis required by the type, so a caret never ships without a name. Write it in the page language.- The menu is Base UI's
role="menu"withmenuitems, arrow navigation and typeahead.
Do
- Two native buttons in a
role="group", each half with its own focus ring. EnterorSpaceruns the main action or opens the menu;ArrowDownandArrowUpopen it and move;Escapecloses it and returns focus to the menu half.- A tap target of at least 48px on each half at every size.
Arabic and RTL notes
Mirrors
- The menu half sits at the inline end: the left in Arabic, with no RTL prop.
- The menu aligns to the button's start (the right in Arabic) and takes the button's direction and language, even inside an Arabic island on an English page.
Does not mirror
CaretDownpoints down, so it never mirrors, even if you swap in a directional icon.
- Numerals
- Numbers in the label or menu items (“Export 3 files”) are formatted with
formatNumber. - Arabic typography
- Labels are
body-16(body-14atxs) Semibold like Button; menu items arebody-16in 48px rows that fit Arabic. - Mixed-direction text
- A Latin format or product name at the end of an Arabic item (“تصدير بصيغة PDF”) reads correctly; in the middle, wrap it in
<bdi>.
Do
- Line the menu up with the inline start of the button in both directions: the left in English, the right in Arabic.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space