RadioGroup

A RadioGroup's selection should only be saved when the user explicitly submits it (e.g., via a "save" button). RadioGroup's are a single tab stop with arrow-key navigation, meaning screen readers can only read an option by selecting it. See saving pattern guidelines for details.

Alternatively, use a SegmentedControl for immediate selection when it's outside a larger form.

Accessibility and usability expectations

Presentation

Cognition

• Radio buttons must always be part of a group, with a visible group label that provides context
• If a selection from a RadioGroup is required, this must be indicated in the group label, ideally using text such as “(required)”. While an asterisk meets technical requirements, it may be unclear to some users and difficult for users with low vision to see
• Each radio button must have a clear, descriptive, and permanently visible label so users understand the purpose of each option
• The option label should appear to the right of the radio button

Vision

• The text, including group label, caption, option labels, and error/success messages, must meet a minimum contrast ratio of 4.5:1
• The radio button’s border must have a minimum contrast ratio of 3:1 against the background
• A custom visible focus style must be implemented. This style must have a minimum contrast ratio of 3:1 against the background and should replace the browser's default focus style, which can be hard to see
• Radio buttons must have a distinct selected state that does not rely solely on color
• Text must be resizable, and spacing adjustable, without causing horizontal scrolling or loss of content.

Mobility

• The target size and spacing of radio buttons must be at least 24 by 24 CSS pixels for ease of use by users with limited dexterity

Adaptability

• Text resizing and spacing adjustments must be supported
• Content must remain readable and not require horizontal scrolling to read or operate it, at a viewport size of 320 by 256 CSS pixels

Interaction

Keyboard

• A radio button must not trap focus or trigger a context change when focused or selected
• Unless disabled, each radio button must be focusable
• A group of radio buttons should have a single tab stop, with arrow keys used to navigate between options and make a selection

Engineering for AT Compatibility

Screen reader

• Each radio button must have an associated <label> to provide an accessible name
• Additional instructions or captions must be programmatically associated with the <input> or <fieldset> using aria-describedby
  • Captions that apply to a specific button should be associated with the <input>
  • Captions or error messages applying to the group should be associated with the <fieldset>
• A group of radio buttons must:
  • Be placed inside a <fieldset> with a <legend> providing the group label, or
  • Be inside a role="region" with an aria-labelledby attribute pointing to the group label
• The selected state must be conveyed to screen readers so that users understand which option is selected
• If a radio button is disabled, that state must also be communicated to screen readers
• Each radio button must have the correct role (radio) so screen readers announce the proper control type

Speech recognition

• The accessible name of each radio button must include the visible label text, enabling speech recognition users to activate a button by saying its visible label

Built-in accessibility features

• The text, radio button border and custom focus style meet minimum contrast requirements
• The radio buttons have a distinct selected state that does not rely solely on color
• The radio buttons have sufficient spacing to meet the minimum target and spacing size of 24 by 24 CSS pixels
• The text is resizable and the text spacing adjustable. The component reflows when zoomed or viewed at a width equivalent to 320 CSS pixels
• By default, the component renders a <fieldset> and <legend> to provide the grouping and group label, but can also use aria-labelledby and role="group"
• The component renders correctly associated pairs of <label> and <input type="radio">. Using the the native <input type="radio"> ensures that the radio buttons conveys the correct role and selected state to screen readers and has the correct keyboard behavior
• The group caption, error message and success message is automatically associated with the <fieldset> using aria-describedby. Option captions are automatically associated with the with the relevant <input>
• When a radio button is disabled, the disabled attribute is applied and the disabled state conveyed to screen readers

Implementation requirements

• Ensure the RadioGroup has a visible group label that provides context. The simplest way to do this is to use a RadioGroup.Label. Alternatively, an aria-labelledby that references an external label can be applied to RadioGroup
• RadioGroup.Label has a visuallyHidden prop, but this should not be used
• When using an icon for a leading visual, note that the icon doesn't have a text alternative. They are purely visual, and not conveyed to screen readers. Don't rely on these icons alone to convey meaning – make sure that the text label of the radio button provides sufficient meaning on its own

How to test the component

Integration tests

• The RadioGroup has a visible group label that provides a descriptive accessible name
• Each radio button has a clear and visible label that describes it's purpose
• If a radio button includes a leading visual icon, the input's purpose is clear from the text label alone

Component tests

• When a RadioGroup is given a RadioGroup.label, a <fieldset> containing a <legend> as the first child is rendered
• When a RadioGroup has an aria-labelledby applied, instead of a RadioGroup.label, a <div> with a role="group" and an aria-labelledby is rendered instead of a <fieldset> and <legend>
• The component renders correctly associated pair of <label> and <input type="radio">
• All text, including labels, captions, error and success messages, meets the minimum contrast requirements of 4.5:1
• The radio button border, selected style and custom focus style meet the minimum contrast requirement of 3:1
• The radio buttons have sufficient spacing to meet the minimum target and spacing size of 24 by 24 CSS pixels
• The content remains readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels
• If there is a group caption, it is associated with the <fieldset> using aria-describedby
• If there is option caption, it is associated with the appropriate <input> using aria-describedby
• If a radio button is disabled, the disabled attribute is present