[MenuItem] add `aria-checked` for checkbox and radio menu items by siriwatknp · Pull Request #48651 · mui/material-ui

siriwatknp · 2026-06-10T10:27:44Z

Summary

Makes MenuItem expose correct ARIA for checkable menus, following the WAI-ARIA menu pattern (items use menuitemcheckbox/menuitemradio + aria-checked).

When role is menuitemcheckbox or menuitemradio, the existing selected prop drives aria-checked. No new prop, no breaking changes.

Behavior

Markup	Result
`<MenuItem role="menuitemcheckbox" selected />`	`aria-checked="true"`
`<MenuItem role="menuitemcheckbox" />`	`aria-checked="false"` (unchecked item)
`<MenuItem role="menuitemradio" selected />`	`aria-checked="true"`
`<MenuItem selected />` (no role)	unchanged — `role="menuitem"`, presentational only, no ARIA state
`Select` options (`role="option"`)	unaffected — no `aria-checked`

For checkbox/radio roles, selected drives aria-checked (omitted selected ⇒ aria-checked="false"), and no aria-selected is emitted.
selected stays presentational for other roles, so existing menus and Select are untouched.

Docs

New Checkbox and radio menu items section in the Menus page with two demos:

CheckboxMenu — independent toggles (menuitemcheckbox).
RadioMenu — single choice in a group (menuitemradio), using radio-button icons.

Tests

selected drives aria-checked (true/false) for menuitemcheckbox and menuitemradio, with no aria-selected.
menuitemcheckbox with selected omitted → aria-checked="false".
non-checkable roles (e.g. option) keep selected presentational, no aria-checked.
plain <MenuItem selected /> keeps role="menuitem" with no ARIA state.

code-infra-dashboard · 2026-06-10T10:33:25Z

Deploy preview

docs/data/material/components/menus/menus.md

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+83B^(+0.02%)	🔺+55B^(+0.04%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/private-theming	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Check out the code infra dashboard for more information about this PR.

mj12albert · 2026-06-10T12:02:16Z

+  // A boolean `checked` turns the item into a checkable control, so expose the matching ARIA
+  // semantics. An explicit `role` is preserved (e.g. `menuitemradio`). Independent from `selected`.
+  const isCheckable = typeof checked === 'boolean';
+  const role = roleProp ?? (isCheckable ? 'menuitemcheckbox' : 'menuitem');


Menu items should either be menuitemcheckboxs or menuitems, this logic dynamically changes an arbitrary menuitem in a group of them to a menuitemcheckbox, resulting in something like this which doesn't seem valid:

role="menu" role="menuitem" role="menuitem" role="menuitemcheckbox" // "checked" role="menuitem"

Reference: https://master--base-ui.netlify.app/react/components/menu#checkbox-items

I decided to change to a simpler approach, to add aria-checked only if user provide explicit role as menuitemcheckbox or menuitemradio.

siriwatknp · 2026-06-10T13:11:02Z

+  // `menuitemcheckbox`/`menuitemradio` require `aria-checked`; derive it from `selected`
+  // (an omitted `selected` means unchecked). Other roles keep `selected` presentational.
+  const isCheckableRole = role === 'menuitemcheckbox' || role === 'menuitemradio';
+  const ariaChecked = isCheckableRole ? Boolean(props.selected) : undefined;
+


@mj12albert do you think this is a nice enhancement to auto added aria-checked?

I think it's a necessity as nobody will bother doing it 😆

mj12albert · 2026-06-11T00:14:14Z

@siriwatknp Did you consider adding a MenuCheckboxItem component? Setting role="menuitemcheckbox" doesn't feel like setting a deliberate prop, and menuitemcheckbox/radio don't look nice

mj12albert · 2026-06-11T00:09:35Z

    ref,
    disabled: props.disabled,
    focusableWhenDisabled: itemsFocusableWhenDisabled,
    selected: props.selected,


For menuitemcheckbox this wouldn't work if multiple checkboxes are initially checked

selected controlled by the consumer. What do you mean by "this wouldn't work"?

Sorry not it's not specific to multiple initially checked checkboxes:

<Menu open> <MenuItem variant="checkbox">1</MenuItem> <MenuItem variant="checkbox" selected>2</MenuItem> <MenuItem variant="checkbox">3</MenuItem> </Menu>

When it's coupled to roving focus's "selected", by making item 2 here initially checked, I think initial focus will land on 2 instead of 1, but the correct behavior should be: initial focus 1?

mj12albert · 2026-06-11T00:11:30Z

+  // `menuitemcheckbox`/`menuitemradio` require `aria-checked`; derive it from `selected`
+  // (an omitted `selected` means unchecked). Other roles keep `selected` presentational.
+  const isCheckableRole = role === 'menuitemcheckbox' || role === 'menuitemradio';
+  const ariaChecked = isCheckableRole ? Boolean(props.selected) : undefined;
+


I think it's a necessity as nobody will bother doing it 😆

siriwatknp · 2026-06-11T08:55:30Z

@siriwatknp Did you consider adding a MenuCheckboxItem component? Setting role="menuitemcheckbox" doesn't feel like setting a deliberate prop, and menuitemcheckbox/radio don't look nice

Let me try it

siriwatknp · 2026-06-15T03:47:33Z

@siriwatknp Did you consider adding a MenuCheckboxItem component? Setting role="menuitemcheckbox" doesn't feel like setting a deliberate prop, and menuitemcheckbox/radio don't look nice

I think exposing 2 more components are overkill, how about adding variant prop to the MenuItem?

<MenuItem variant="item"> // default
<MenuItem variant="checkbox">
<MenuItem variant="radio">

mj12albert · 2026-06-15T07:34:06Z

how about adding variant prop to the MenuItem

Generally our variant prop indicates visual variants (e.g. primary vs secondary button) with no functional differences, but in this case both visuals and functionality are changed so I'm not sure it's the best fit?
WDYT @silviuaavram

siriwatknp · 2026-06-15T08:34:03Z

how about adding variant prop to the MenuItem

Generally our variant prop indicates visual variants (e.g. primary vs secondary button) with no functional differences, but in this case both visuals and functionality are changed so I'm not sure it's the best fit? WDYT @silviuaavram

good point, then may be a type prop? I think using a prop is better in this case, it's just naming to decide.

well, if naming is too hard. I rather switch back to the role prop. Consumer gets autocomplete anyway, I don't think having an alias prop is worth it.

For role=menuitemcheckbox or menuitemradio, the selected prop sets aria-checked (omitted selected means unchecked); other roles keep selected presentational. No new prop, no breakage. Add docs section with menuitemcheckbox and menuitemradio demos.

silviuaavram · 2026-06-16T12:00:22Z

      "description": "This prop can help identify which element has keyboard focus. The class name will be applied when the element gains the focus through keyboard interaction. It&#39;s a polyfill for the <a href=\"https://drafts.csswg.org/selectors-4/#the-focus-visible-pseudo\">CSS :focus-visible selector</a>. The rationale for using this feature <a href=\"https://github.com/WICG/focus-visible/blob/HEAD/explainer.md\">is explained here</a>. A <a href=\"https://github.com/WICG/focus-visible\">polyfill can be used</a> to apply a <code>focus-visible</code> class to other components if needed."
    },
-    "selected": { "description": "If <code>true</code>, the component is selected." },
+    "selected": {


is this API consistent with other such examples in the library?

if we want to keep this stateless, why not just create an example with both role and aria-checked passed directly by the users? we're not helping much with the selected prop, we just translate it for them.

the other option in my opinion is go stateful, and manage the checked state ourselves. in this case, we probably need a Context wrapper and maybe new component wrapping MenuItem: MenuItemCheckbox and MenuItemRadio or something.

what do you think? @siriwatknp @mj12albert

Re-using the name selected for checkbox/radio items adds indirection because you typically think of them as "checked" and not "selected".

Additionally if the API was to switch components via prop (e.g. MenuItem variant="checkbox"), "selected" could influence any of these 3 things depending on the component:

styling - whether .Mui-selected is added or not

the aria-checked state

the initial focus target - when the selected prop is passed into the roving focus hook

which could get hard to reason about when it's coupled to combinations of the variant and selected props, does that make sense?

So having new checkbox/radio item components gives us a way out of some restrictions/shortcomings of the current API

siriwatknp added scope: menu Changes related to the menu. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. package: material-ui Specific to Material UI. labels Jun 10, 2026

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from 8c34236 to 0b9b296 Compare June 10, 2026 11:46

siriwatknp changed the title ~~[MenuItem] Add menuitemcheckbox role and aria-checked for selected items~~ [MenuItem] Add checked prop with menuitemcheckbox role and aria-checked Jun 10, 2026

mj12albert reviewed Jun 10, 2026

View reviewed changes

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from 0b9b296 to 2627aaf Compare June 10, 2026 12:08

siriwatknp changed the title ~~[MenuItem] Add checked prop with menuitemcheckbox role and aria-checked~~ [MenuItem] Support menuitemcheckbox/menuitemradio with aria-checked Jun 10, 2026

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from 2627aaf to fb6e545 Compare June 10, 2026 12:28

siriwatknp commented Jun 10, 2026

View reviewed changes

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from fb6e545 to 64bda4a Compare June 10, 2026 13:12

mj12albert reviewed Jun 11, 2026

View reviewed changes

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from 64bda4a to 1124569 Compare June 15, 2026 03:55

siriwatknp changed the title ~~[MenuItem] Support menuitemcheckbox/menuitemradio with aria-checked~~ [MenuItem] Add variant prop for checkbox and radio menu items Jun 15, 2026

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from 1124569 to d632bf6 Compare June 15, 2026 04:04

siriwatknp force-pushed the feat/menuitem-checkbox-role branch from d632bf6 to 8d8b43f Compare June 16, 2026 03:41

siriwatknp changed the title ~~[MenuItem] Add variant prop for checkbox and radio menu items~~ [MenuItem] Support menuitemcheckbox/menuitemradio with aria-checked Jun 16, 2026

siriwatknp changed the title ~~[MenuItem] Support menuitemcheckbox/menuitemradio with aria-checked~~ [MenuItem] add aria-checked for checkbox and radio menu items Jun 16, 2026

silviuaavram reviewed Jun 16, 2026

View reviewed changes

Uh oh!

Conversation

siriwatknp commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Behavior

Docs

Tests

Uh oh!

code-infra-dashboard Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Bundle size

Uh oh!

mj12albert Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

siriwatknp Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

siriwatknp Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

mj12albert Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

mj12albert commented Jun 11, 2026

Uh oh!

mj12albert Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

siriwatknp Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

mj12albert Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mj12albert Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

siriwatknp commented Jun 11, 2026

Uh oh!

siriwatknp commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mj12albert commented Jun 15, 2026

Uh oh!

siriwatknp commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

silviuaavram Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

mj12albert Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

siriwatknp commented Jun 10, 2026 •

edited

Loading

code-infra-dashboard Bot commented Jun 10, 2026 •

edited

Loading

siriwatknp Jun 10, 2026 •

edited

Loading

mj12albert Jun 15, 2026 •

edited

Loading

siriwatknp commented Jun 15, 2026 •

edited

Loading

siriwatknp commented Jun 15, 2026 •

edited

Loading

mj12albert Jun 16, 2026 •

edited

Loading