Amenuitemradio is checkable menuitem in a set of elements with the same role, only one of which can be checked at a time.

Description

The items in menu and menubars are menu items. There are three types of menu items:menuitem,menuitemcheckbox, andmenuitemradio. To limit the number of checked menu items to one within a group, use themenuitemradio role on all the elements in the group.

Amenuitemradio is checkable menuitem in a set of elements with the same role, of which only can be checked at a time.

The three menu item elements can only be contained in, or owned by, an element with rolemenu ormenubar, optionally nested within a grouping element with role ofgroup. Being nested or otherwise owned (seearia-owns) in amenu ormenubar identifies the menu items as being related widgets.

When all items in a submenu are members of the same radio group, thegroup is defined by the menu element; thegroup element is not necessary.

Menu items containing the role ofmenuitemradio must include thearia-checked attribute to expose the radio button's state to assistive technology, unless using<input type="radio">, in which case thechecked attribute should be used.

Similar to thechecked attribute of<input>s of typeradio, thearia-checked attribute of amenuitemradio indicates whether the menu item is checked (true), unchecked (false). There is nomixed value like there is formenuitemcheckbox.

Only onemenuitemradio in a group can be checked at the same time. When one item in the group is checked, thearia-checked attribute gets set totrue, while the previously checkedmenuitemradio element in the same group, if there was one, becomes unchecked, by having thearia-checked attribute value switched tofalse.

If your want more than one item in a group to be checked, or if you want to enable checking and unchecking an item, consider usingmenuitemcheckbox.

If amenu ormenubar contains more than one group ofmenuitemradio elements, or if themenu contains a group ofmenuitemradio elements as well as other, unrelatedmenuitem elements and/ormenuitemcheckbox elements, contain each set of relatedmenuitemradio elements in agroup element or delimit the group themenuitemradio elements from the other menu items with aseparator element (or an HTML element with an equivalent role such as a<fieldset> grouping or a thematic break<hr> separator.

An accessible name is required. Ideally, the accessible name should come from an associated<label> element if using<input type="radio"> or visible, descendant content. Realize if the label or descendant content is not sufficient and, preferably,aria-labelledby is used referencing non-descendant content oraria-label is used, these two ARIA properties will hide other descendant content from assistive technologies.

If all elements in the set are not present in the DOM include thearia-setsize andaria-posinset properties. When specifyingaria-setsize andaria-posinset on amenuitemradio, set the value with respect to the total number of items in the menu, excluding any separators.

Themenuitemradio element can have phrasing content, but can not have interactive content as descendants and no descendants with atabindex attribute specified.

All descendants are presentational

There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in amenuitemradio. To deal with this limitation, browsers, automatically apply rolepresentation to all descendant elements of anymenuitemradio element as it is a role that does not support semantic children.

For example, consider the followingmenuitemradio element, which contains a heading.

<div role="menuitemradio"><h6>Name of my radio button</h6></div>

Because descendants ofmenuitemradio are presentational, the following code is equivalent:

<div role="menuitemradio">  <h6 role="presentation">Name of my radio button</h6></div>

From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in theaccessibility tree:

<div role="menuitemradio">Name of my radio button</div>

Associated WAI-ARIA roles, states, and properties

menu role

Widget that offers a list of common actions or functions the user can invoke.

menubar role

Similar tomenu for a consistent set of frequently used commands remaining visible and usually presented horizontally.

group role

Container for a group ofmenuitem elements, includingmenuitemradio elements within amenu ormenubar.

aria-checked (Required)

Set totrue orfalse, it indicates the current "checked" state of the menuitemradio

Keyboard interactions

When amenu opens, or when amenubar receives focus, keyboard focus is placed on the first item. All items in both are focusable, including allmenuitemradio elements.

If themenuitemradio is in a submenu in amenubar or a menu opened with a menu button, the following keyboard interactions must be programmed in. :

Enter

If not checked, checks the focusedmenuitemradio and unchecks any other checkedmenuitemradio element in the same group. Also, closes the menu.

Space

If not checked, checks the focusedmenuitemradio and unchecks any other checkedmenuitemradio element in the same group without closing the menu.

Escape

Closes menu. In menubar, moves focus to parent menubar item.

Right Arrow

Closes submenu. In menubar, moves focus to next item in the menubar, opening any submenu if there is one.

Left Arrow

Closes menu. In menubar, moves focus to previous item in the menubar, opening any submenu if there is one.

Down Arrow

Moves focus to the next item in the menu. If focus is on the last item, moves focus to the first item.

Up Arrow

Moves focus to previous item in the menu. If focus is on the first item, moves focus to the last item.

Home

Moves focus to the first item in the menu.

End

Moves focus to the last item in the menu.

Character

Moves focus to the next item having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move.

Required JavaScript

Required event handlers

onclick

Handle mouse clicks on both the radio button and the associated label that will change the state of the radio button by changing the value of thearia-checked attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user

onKeyDown

Handle the case where the user presses theSpace key to change the state of the radio button by changing the value of thearia-checked attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user. Also handles all keys listed in the keyboard navigation section above.

Examples

<li role="menuitemradio" tabindex="-1" aria-checked="false">Purple</li>

Thetabindex="-1" makes themenuitemradio focusable but not part of the page tab sequence. Had we includedaria-checked="true" it would have indicated that themenuitemradio was checked, and we would have visually styled the selected state to look checked using the attribute selector[role='menuitemradio'][aria-checked='true']. Instead, the presence ofaria-checked="false" indicates to assistive technologies that themenuitemradio is checkable but not currently checked. The accessible name "purple" comes from the contents.

The visual appearance of the selected state is a checked radio button which we can create usinggenerated content, making it visible and the same color as the content by synchronizing with thearia-checked value using CSSattribute selectors and changing thebackground-color.

[role="menuitemradio"]::before {  display: inline-block;  content: "";  width: 1em;  height: 1em;  padding: 0.1em;  border: 2px solid #333333;  border-radius: 50%;  box-sizing: border-box;  background-clip: content-box;  margin-inline-end: 2px;}[role="menuitemradio"][aria-checked="true"]::before {  background-color: purple;}

Don't use thebackground shorthand property, as that will override thebackground-clip property we used to create the radio button effect.

Prefer HTML

The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the nativeHTML radio button form control instead of recreating a radio button's functionality with JavaScript and ARIA.

Specifications

See also

• radio role
• <input type="radio">