@fluentui/react-radio Spec

A Radio allows a user to select a single value from two or more options. All Radios with the same name are considered to be part of the same group. However, a RadioGroup is recommended to add a group label, formatting, and other functionality.

Background

Prior Art

• OpenUI research
• Epic

Comparison of Fabric ChoiceGroup and Stardust RadioGroup

• All mentions of v7 or v8 refer to Fabric - @fluentui/react (docsite)
• All mentions of v0 refer to Northstar - @fluentui/react-northstar (docsite)

See Appendix for a detailed comparison of the two components.

In Fabric the Radio component is represented by the ChoiceGroup component. Fabric creates options based on data passed in via the options prop. It uses the option's key property as the input value and holds the currently selected value in the selectedKey prop. Fabric also allows an image to serve as a label for an option.

<ChoiceGroup
  defaultSelectedKey="B"
  options={[
    { key: 'A', text: 'Option A' },
    { key: 'B', text: 'Option B' },
    { key: 'C', text: 'Option C', disabled: true },
    { key: 'D', text: 'Option D' },
  ]}
  label="Pick one"
  required={true}
/>

In Northstar the Radio component is represented by the RadioGroup component. Northstar creates options based on data passed in via the items prop. It uses the option's value property as the input value and holds the currently selected value in the checkedValue prop.

<RadioGroup
  onCheckedValueChange={handleChange}
  items={[
    { key: '1', label: 'Make your choice', value: '1' },
    { key: '2', label: 'Another option', value: '2' },
  ]}
/>

Variants

Layout

Horizonal

Inline positioning of the inputs and labels.

Horizonal stacked

Positioning the label at the bottom of the radio inputs.

Vertical

Default vertical positioning of Radio items.

Vertical with input

Default positioning of Radio items with an input as its last Radio item.

Vertical with dropdown

Default positioning of Radio items with a dropdown as its last Radio item.

API

Components

RadioGroup

Link to RadioGroup.types.ts

RadioGroupContext

This is a context object provided by RadioGroup that allows all of the child Radio items to have the same name, and coordinate the selected item.

The context contains the following props from RadioGroup:

• name
• layout
• defaultValue
• value
• disabled

Radio

Link to Radio.types.ts

Sample Code

A simple RadioGroup.

<RadioGroup defaultValue="one">
  <Radio value="one" label="Option One" />
  <Radio value="two" label="Option Two" />
  <Radio value="three" label="Option Three" />
</RadioGroup>

Radio can be used without a RadioGroup, but it is then up to the user to add the same name to each item:

<>
  <Radio name="number" value="one" label="Option One" defaultChecked />
  <Radio name="number" value="two" label="Option Two" />
  <Radio name="number" value="three" label="Option Three" />
</>

Structure

Expected DOM structure

<div role="radiogroup" class="fui-RadioGroup" name="radiogroup-0">
  <span class="fui-Radio">
    <input type="radio" id="radio-1" name="radiogroup-0" value="one" checked />
    <div class="fui-Radio__indicator">
      <svg><circle /></svg>
    </div>
    <label class="fui-Label" for="radio-1">Option One</label>
  </span>

  <span class="fui-Radio">
    <input type="radio" id="radio-2" name="radiogroup-0" value="two" />
    <div class="fui-Radio__indicator">
      <svg><circle /></svg>
    </div>
    <label class="fui-Label" for="radio-2">Option Two</label>
  </span>

  <span class="fui-Radio">
    <input type="radio" id="radio-3" name="radiogroup-0" value="three" />
    <div class="fui-Radio__indicator">
      <svg><circle /></svg>
    </div>
    <label class="fui-Label" for="radio-3">Option Three</label>
  </span>
</div>

Behaviors

Mouse/Touch

The Radio's hit target fills the entire space around the indicator and label (including the padding).

Keyboard

RadioGroup inherits all of its mouse and keyboard behaviors from the browser's handling of <input type="radio">.

• It has no special handling of clicks or keypresses for toggling beyond the built-in control.
• The browser handles arrow key selection, and creating a single tab stop for the control.

Disabled

• Individual Radio items can be disabled, in which case they are grayed out and can't be selected or focused.
  • This interaction is built-into the browser by setting disabled on the <input> control.
• The entire RadioGroup can be disabled, which uses RadioGroupContext to disable all of the individual Radio items.

Group Name

• All Radio items in a group must have the same name for the browser to handle keyboarding and selection.
• The RadioGroup provides its name through RadioGroupContext, and each Radio inside applies the name.
• If a name is not provided on RadioGroup, a unique name is automatically generated with useId.

Accessibility

RadioGroup

This implementation based on the Grouping Controls examples of Web Accessibility Tutorials (that follow WCAG).

• The RadioGroup root is a <div role="radiogroup"> to provide the default accessibility behavior of a radiogroup.
• If a group label is added, the RadioGroup needs to have aria-labelledby referencing the label.

Radio

• The Radio's primary slot is an <input type="radio">, with opacity 0, and covers the root.
  • This way, the Radio's hit target fills the entire space around the indicator and label (including the padding).
• The Radio's label is a <label> element with for={input.id} to associate it with the input slot.

Appendix

v8 vs v0 comparison

RadioGroup (v0) vs ChoiceGroup (v8) prop mapping

⚠️ Props not included in this section are marked as deprecated and will not be considered.

RadioItem (v0) vs ChoiceGroupOption (v8) props mapping