aria: radiogroup role

The radiogroup role is a group of radio buttons.

Description

Radio groups are collections describing a set of related radio options. A radiogroup is a type of select list that can only have a single entry, or radio, checked at any one time.

When using HTML's native input radio button, <input type="radio">, the radio buttons are grouped when each of input radio buttons in the group is given the same name. Once a group of same-named input radio buttons is established, selecting any input radio button in that group automatically deselects any currently-selected input radio button in the same group. While this will associate the radio buttons together, to expose a grouping of radio buttons as a radiogroup explicitly set the ARIA role.

It is recommended to create radio groups by using same-named HTML input radio buttons, but, if you must use ARIA roles and attributes instead of semantic HTML form controls, custom radio buttons can and should act like native HTML radio input buttons.

When using non-semantic elements as radio buttons, you must ensure your users can only select one radio button from the group at a time. When one item in the group is checked, having their aria-checked attribute set to true, the previously checked item becomes unchecked, with its aria-checked attribute becoming false. The aria-checked attribute is set on the associated radio roles, not on the radiogroup itself.

Some radiogroup implementations initialize the set with all buttons in the unchecked state. Once a radio in a radiogroup is checked, it is generally not possible to return to an all-unchecked state.

The radiogroup must have an accessible name either by a visible label referenced by aria-labelledby or has a label specified with aria-label. If elements provide additional information about the radio group, those elements are referenced by the radiogroup element with the aria-describedby property.

Associated WAI-ARIA roles, states, and properties

radio role

One of a group of checkable buttons, in a radiogroup, where no more than one of the buttons can be checked at a time.

aria-labelledby / aria-label

The radiogroup must have an accessible name either by a visible label referenced by aria-labelledby or has a label specified with aria-label.

aria-describedby

Reference to elements providing additional information about the radiogroup

aria-required

Indicates that one radio within the group must have aria-checked="true" set before the form may be submitted. The required state is specified on the radiogroup element rather than one of the radio elements, unlike when using HTML radio buttons where the required attribute is set directly on one or more radio <input> elements.

aria-errormessage

Identifies the element that provides an error message for the radiogroup, if there is an error. That message should be hidden while not relevant.

Keyboard interactions

For radio buttons in a radiogroup that is NOT in a toolbar, the following keyboard interactions must be supported:

Tab and Shift + Tab

Move focus into and out of the radiogroup. When focus moves into a radiogroup, if a radio button is checked, focus is set on the checked button. If none of the radio buttons are checked, focus is set on the first radio button in the group.

Space

Checks the focused radio button if it is not already checked.

Right Arrow and Down Arrow

Moves focus to the next radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the last button, focus moves to the first button.

Left Arrow and Up Arrow

Moves focus to the previous radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the first button, focus moves to the last button.

Arrow keys are used to navigate among elements of a toolbar. When a radiogroup is nested inside a toolbar, users need to be able to navigate among all toolbar elements, including the radio buttons, without changing which radio button is checked. So, when navigating through a radiogroup in a toolbar with arrow keys, the button that is checked does not change. Rather, when inside a toolbar, the Space and Enter keys check the focused radio button if it is not already checked, with Tab moving focus into and out of the toolbar.

Required JavaScript features

User interactions for radiogroups must replicate the user interaction of a user entering into a group of same-named HTML radio buttons. Keyboard events for tabs, space, and arrow keys must be captured. Click events on both the radio elements and their associated labels must also be captured. Additionally, focus must be managed.

While generally moving off an a focused element brings you to the next focusable element in the DOM order, using the arrow keys to navigate thru a group of radio button keeps you in the group, moving focus to the first radio button when the Right Arrow or Down Arrow is released when focus was on the last radio in the group, and moving to the last radio if the Left Arrow or Up Arrow is released if focus was on the first radio. Managing roving tabindex is one method to manage arrow key events.

Required CSS features

Use the [aria-checked="true"] attribute selector to style the checked state of checked radio buttons.

Use CSS :hover and :focus pseudo-classes for styling visual keyboard focus and hover. The focus and hover effect should encompass both the radio button and label to make it easier to perceive which option is being chosen and to indicate that clicking either the label or button will activate the radio button.

Examples

The basic set up for a radiogroup using non-semantic ARIA roles instead of semantic HTML is as follows:

<div role="radiogroup" aria-labelledby="question">
  <div id="question">
    Which is the best color?</div>
  <div id="radioGroup">
    <p>
      <span id="colorOption_0" tabindex="0"
        role="radio" aria-checked="false" aria-labelledby="purple"></span>
      <span id="purple">Purple</span>
    </p>
    <p>
      <span id="colorOption_1" tabindex="-1"
        role="radio" aria-checked="false"  aria-labelledby="aubergine"></span>
      <span id="aubergine">Aubergine</span>
    </p>
    <p>
      <span id="colorOption_2" tabindex="-1"
        role="radio" aria-checked="false" aria-labelledby="magenta"></span>
      <span id="magenta">Magenta</span>
    </p>
    <p>
      <span id="colorOption_3" tabindex="-1"
        role="radio" aria-checked="false" aria-labelledby="all"></span>
      <span id="all">All of the above</span>
    </p>
  </div>
</div>

This could have been written using semantic HTML, which requires no CSS or JavaScript:

<fieldset>
  <legend>Which is the best color?</legend>
  <p>
    <input name="colorOption" type="radio" id="purple">
    <label for="purple">Purple</label>
  </p>
  <p>
    <input name="colorOption" type="radio" id="aubergine">
    <label for="aubergine">Aubergine</label>
  </p>
  <p>
    <input name="colorOption" type="radio" id="magenta">
    <label for="magenta">Magenta</label>
  </p>
  <li>
    <input name="colorOption" type="radio" id="all">
    <label for="all">All of the above</label>
  </p>
</fieldset>

In this <fieldset> example, while role="radiogroup" is not necessary, to have this grouping explicitly announced as radiogroup, include the ARIA role.

Specifications

Specification
Accessible Rich Internet Applications (WAI-ARIA)
# radiogroup
ARIA Authoring Practices
# radiobutton

See Also