Role and semantics
Section titled “Role and semantics”SplitButton is two separate button elements. The main button is named by its visible label. The menu button is drawn with Base UI Menu: it carries aria-haspopup="menu" and aria-expanded; its name comes from menuLabel, required at type level because the button shows only an icon. The list is role="menu" and its items are role="menuitem". The chevron and item icons carry aria-hidden.
Keyboard
Section titled “Keyboard”| Key | Behaviour |
|---|---|
| Tab | Moves to the main button, then to the menu button. |
| Enter or Space | On the main button runs the action; on the menu button opens the menu. |
| Down arrow | On the menu button opens the menu and moves to the first item. |
| Up and down arrow | Moves between items in the menu. |
| Home and End | Moves to the first and last item. |
| A letter | Moves to the item that starts with it. |
| Escape | Closes the menu; focus returns to the menu button. |
Disabled items can be reached with the arrow keys but cannot be chosen.
Both buttons show a 2 px color-focus-ring ring on keyboard focus only. When the menu opens focus moves to the first item; when it closes focus returns to the menu button.
Screen reader output
Section titled “Screen reader output”| Example | Read as |
|---|---|
| Main button | “Save, button” |
| Menu button | “More save options, menu button, collapsed” |
| Menu open | “Save as draft, menu item, 1 of 2” |
| Disabled item | “Save as copy, menu item, dimmed” |
Contrast
Section titled “Contrast”Labels and the chevron use the Button colours and keep at least 4.5:1 contrast. The primary divider is decorative; the border between the parts is also clear from the focus ring and the separate hit areas. The disabled state is exempt (WCAG 1.4.3).
WCAG 2.2
Section titled “WCAG 2.2”| Criterion | How SplitButton meets it | What the product team must do |
|---|---|---|
| 1.3.1 Info and relationships | menu and menuitem roles, aria-haspopup. |
Put only related actions in the menu. |
| 2.1.1 Keyboard | Both buttons are tab stops; arrow keys move through the menu. | Do not add your own key handlers. |
| 2.4.3 Focus order | Focus enters the menu and returns to the menu button. | Do not move focus elsewhere after a choice. |
| 2.4.7 Focus visible | focus-visible ring. |
Do not remove the ring. |
| 2.5.8 Target size (minimum) | The smallest menu button is 32 × 32 px. | Use md or lg on touch screens. |
| 4.1.2 Name, role, value | The name comes from menuLabel, the state from aria-expanded. |
Give a meaningful menuLabel. |