Skip to content

Split Button

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add split-button

    Also works with shadcn: npx shadcn@latest add @ritla/split-button

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or 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

split-button.tsx
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.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

Menu and keyboard

Tab moves between the halves. The menu half opens with Enter, Space or ArrowDown, and the menu lines up with the start of the whole button: the right in Arabic. Try the Arabic mode.

EnglishMirroredArabic
LTR →

Disabled

disabled switches off both halves together.

EnglishMirroredArabic
LTR →

API reference

SplitButton

Other Base UI Button props (onClick, type…) go to the main action half.

PropTypeDefaultDescription
childrenReactNodeNoneFigma's Label: the main action's text.
menuLabelstringNoneRequired. The menu half's name for screen readers (“More save options”).
menuReactNodeNoneSplitButtonItems 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.
iconLeadingIconComponentNoneIcon leading: an icon before the label.
trailingIconIconComponentCaretDownIconTrailing btn icon. It never mirrors.
disabledbooleanfalseState = Disabled on both halves.
classNamestringNoneClasses 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.

PropTypeDefaultDescription
childrenReactNodeNoneThe action's text.
onClick(event) => voidNoneCalled on selection; the menu then closes.
disabledbooleanfalseDisables the item and keeps it visible.

Anatomy

The parts of a split button and where each one lives in Figma and in code.

  1. 1. Grouprole="group"Two halves with a space-2 gap, laid out inline. In Outline the halves share one border, with no gap.
  2. 2. Leading buttonchildren, iconLeadingThe label and an optional leading icon, corners at the inline start. Its own focus stop; other Button props go here.
  3. 3. Trailing buttontrailingIconA square menu half with the CaretDown swap: the menu trigger, with aria-haspopup and aria-expanded. Never mirrors.
  4. 4. Menu label (not drawn)menuLabelA hidden text property, required: the accessible name of the menu half.
  5. 5. MenumenuRitla UI menu items 12px under the button, at its inline start; role="menu".
  6. 6. Touch targetsize/touch-targetsm and xs keep 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: Variations of SaveEvery item is a way of saving, so the split reads as one action.
Don't: Unrelated actionsShare, Delete and Settings are not variations of Save. Use a Menu button.

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.

2. Name the menu half

menuLabel is required in code, so a caret never ships without a name. In Figma, fill the hidden Menu label property (More save options), in the page language.

3. Keep the label short

The label is the main action; the details belong in the menu.

An export bar

Exporting a report.

Do: ExportOne verb; the formats sit in the menu.
Don't: Export as PDF for printingLong labels push the menu half away and repeat the menu.

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.

Do: outline Cancel, filled SaveThe main action stands out.
Don't: Two 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.

Do: RTL = YesThe label reads first and the menu half closes the line on the left.
Don't: RTL = No with Arabic textThe caret lands before the label and the order reads backwards.

Before handoff

  • Label and Menu label are filled in the page language.
  • Menu items are variations of the main action.
  • One filled per 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.

SizeHeight, padding, radiusLabel and icons
lg56 · space-24 · radius/10body-16/Semibold · 24
md48 · space-24 · radius/10body-16/Semibold · 20
sm40 · space-16 · radius/8body-16/Semibold · 20
xs32 · space-12 · radius/6body-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.

StyleFill and borderLabel and icons
filledbackground/brand/solidtext/brand/on-brand
tonalbackground/brand/fainttext/brand/subtle
outlinebackground/surface/lowest · border/gray/softtext/gray/subtle
ghostalpha/tint-12text/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.

KeyAction
TabMoves from the main action to the menu half; each half shows its own ring.
EnterSpaceRuns the main action, or opens the menu from the menu half.
ArrowDownArrowUpOpens the menu and moves between its items.
EscapeCloses the menu and returns focus to the menu half.

ARIA

  • Two native buttons in a role="group"; the menu half carries aria-haspopup="menu" and aria-expanded.
  • menuLabel is 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" with menuitems, arrow navigation and typeahead.

Do

  • Two native buttons in a role="group", each half with its own focus ring.
  • Enter or Space runs the main action or opens the menu; ArrowDown and ArrowUp open it and move; Escape closes 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

  • CaretDown points 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-14 at xs) Semibold like Button; menu items are body-16 in 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.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space