Skip to content

SplitButton

C-30 · Components · Editor (Office)

All elements · SplitButton on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for SplitButton.

SplitButton

C-30 OfficeWCAG 2.2 AA · Passed

A primary action and a menu half sharing one hover outline (Fluent v9 pattern): two buttons in the roving order; the menu half is named "More options for …". A toggle split carries aria-pressed on the primary; a color split shows its current color in __swatch.

Axis / element Values
.qf-split-button__primary · __menu the two halves
__glyph · __swatch icon with a color bar (font color, highlight, fill)
data-size sm · md (default) · lg
data-layout="stacked" Full large: the label sits in the menu half
Sizes

Guidance

When to use

  • Use it in an office editor ribbon or mini toolbar when one command has a default action and a short list of variants, such as Paste and its paste options.
  • Use the toggle form when the primary half turns a format on and off and the menu picks its style, such as Underline and Double underline.
  • Use the color form for font color, highlight and fill, where the primary applies the last color shown in __swatch and the menu opens the Color picker.
  • Use data-layout="stacked" at data-size="lg" for the first command of a Full ribbon group.

When to consider something else

  • When the control only opens a list and has no default action, use a command Button with aria-haspopup="menu" instead. See Button.
  • When several related actions sit side by side with no shared default, use a Button group. See ButtonGroup.
  • When the variants are visual previews, such as styles, use a Gallery instead of a menu half. See Gallery.
  • Outside the office editors, use the standard Menu from a Button; the split button is an Office-era component. See Menu.

Usability

Do
  • Make the primary half run the most common or the last used variant, and keep its name stable.
  • Name the menu half "More options for <command>" so the two halves are told apart.
  • Update __swatch when the user picks a color, so the primary repeats that choice.
  • Put every split button command in the ribbon too when it also appears in the mini toolbar.
  • Use Fluent Regular glyphs from sprites/office-icons.svg inside .qf-office surfaces; never mix in Tabler glyphs there (README, Icons).
Don’t
  • Don't put commands in the menu that are unrelated to the primary action.
  • Don't rely on the swatch color alone to say which color is current; the menu or picker must name it.
  • Don't swap the glyph to show state; state comes from aria-pressed and the pressed background.

Accessibility

Keyboard

SplitButton keyboard
Keys Action
Tab Moves into the toolbar at its single tab stop; the two halves are separate stops in the roving order.
Arrow Left / Arrow Right Moves between the primary half, the menu half and the other toolbar controls.
Enter or Space on the primary Runs the command, or toggles it when the primary carries aria-pressed.
Enter or Space on the menu half Opens the menu and moves focus to its first item.
Arrow Down / Arrow Up, Home, End Moves between menu items while the menu is open.
Escape Closes the menu and returns focus to the menu half.

Roles and names

  • Two native <button> elements inside .qf-split-button; each needs its own accessible name (aria-label when the half shows only an icon).
  • The menu half carries aria-haspopup="menu" and aria-expanded, kept in sync with the open state.
  • A toggle split puts aria-pressed on .qf-split-button__primary only.
  • Icons and the swatch are aria-hidden; the color name belongs in the accessible name or the menu.

Focus

  • Each half shows its own :focus-visible ring; hover outlines the pair as one control.
  • Closing the menu by Escape or by choosing an item returns focus to the menu half.

Other requirements

  • The small size is 1.5rem (24px) high, which meets 2.5.8 Target Size (Minimum); keep the menu half at least that wide.
  • The swatch is a non-text indicator; keep it at 3:1 against the button background or pair it with a border (1.4.11).
  • In forced colors the focus ring is redrawn with system colors; do not suppress it.

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

SplitButton test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (6 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- split-button --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

SplitButton package
Source css/classic/components/commands.css
Specimens also use Box · Button · Card · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes