Radio

Anatomy

1. Form Field Label: The Form Field Label describes all of the Radio in the Radio group and functions as a header.
2. Radio Button: Radio Buttons are vertically aligned and in close proximity to its own label.
3. Radio Label: Radio Labels give information about what to select.

Usage Guidance

• The Form Field Label can be positioned in two places; above or left of Radio group for LTR languages. Form Field Labels are aligned to the right of Radio group for RTL languages.
• Radio Labels are positioned to the right of Radio Buttons for LTR languages or to the left of Radio Buttons for RTL languages.
• You can configure one Radio Button in the group preselected by default. This default option should be the safest option presenting the least risk to the user, or be the option most commonly selected.
• If the user is allowed to not select any of the options, provide a “None” option.
• If the list doesn't encompass all possible values in 7 or less options, provide a Radio Button marked “Other.”

When to Use

• Use Radio Buttons when a user is only allowed to select 1 value from a list of 7 or less options.

When to Use Something Else

• Consider using a Switch if the only options are yes or no.
• If a user is allowed to select 0, 1, or multiple values from a predefined list of 7 or less options, consider using Checkboxes or a Select to select one option.
• Use a Prompt when the number of list items is large or unknown. Prompts have search capabilities and folders which provide users with the means to browse options. Prompts can be configured to support single or multi-select.

Examples

Basic Example

Our radio component includes a RadioGroup container and RadioGroup.RadioButton, which renders an individual radio button. Nest related RadioGroup.RadioButton buttons within a RadioGroup and provide a name prop to the RadioGroup to group the radio buttons together. Each RadioGroup.Radio must have a unique value. This value is used in conjunction with the value prop set on the RadioGroup to determine which radio button is selected. To tie it all together, provide an onChange handler to the RadioGroup to track the selected value as it changes.

RadioGroup should be used in tandem with Form Field where the useFieldset prop is set to true to meet accessibility standards. This ensures the label text from FormField is attached to the RadioGroup and read out as a group for voiceover.

Our example uses React state to track the value of the RadioGroup.

RadioGroup and RadioGroup.Radio support keyboard navigation through the proper use of WAI-ARIA properties.

Inverse

Set the variant prop of RadioGroup.RadioButton to inverse to ensure proper contrast on dark backgrounds.

Radio Group with No Value

Omit the value prop from RadioGroup to render the group with no selected RadioGroup.RadioButton.

Ref Forwarding

RadioGroup.RadioButton supports ref forwarding. It will forward ref to its underlying <input type="radio"> element.

Label Position

Set the labelPosition prop of the wrapping FormField to designate the position of the label relative to the RadioGroup. labelPosition accepts the following values:

• FormField.LabelPosition.Top (Default)
• FormField.LabelPosition.Left

Required

Set the required prop of the wrapping FormField to true to indicate that the field is required. Labels for required fields are suffixed by a red asterisk.

Disabled

Set the disabled prop of RadioGroup.RadioButton to prevent users from interacting with it. Be careful not to disable a pre-selected radio button as this will block keyboard access to the entire RadioGroup.

Custom Radio Button

Use RadioGroup.Label instead of RadioGroup.RadioButton if you need direct access to the label and the radio input. This will allow you to apply custom styling to the text and radio input.

Standalone Radio Button

Use StyledRadioButton when you want a styled radio button on its own without using RadioGroup. You will need to handle behavior and accessibility.

Use RadioGroup.Label when you want more control styling the text and radio input but still want some behavior handled for you.

Error States

Set the error prop of the wrapping FormField to FormField.ErrorType.Alert or FormField.ErrorType.Error to set the RadioGroup to the alert or error state, respectively. You will also need to set the hintId and hintText props on the FormField to meet accessibility standards. You must set an aria-describedby attribute on the RadioGroup element that matches the value of hintId set on the FormField element. These attributes ensure that the alert message is associated to the RadioGroup and read out by voiceover.

Alert

Use the alert state when a selection is valid but there is additional information.

Error

Use the error state when the selection is no longer valid.

React Hook Form

Using a form library like React Hook Form is a common use case. Reference this CodeSandbox on how to use RadioGroup with React Hook Form.

Component API

<RadioGroup name="pizza-crust" value="thin">
  <RadioGroup.RadioButton value="deep-dish">Deep dish</RadioGroup.RadioButton>
  <RadioGroup.RadioButton value="thin">Thin</RadioGroup.RadioButton>
</RadioGroup>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<RadioGroup name="pizza-crust" value="thin">
  <RadioGroup.RadioButton value="deep-dish">Deep dish</RadioGroup.RadioButton>
  <RadioGroup.RadioButton value="thin">Thin</RadioGroup.RadioButton>
</RadioGroup>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<RadioGroup name"pizza-crust" value="deep-dish">
  <RadioGroup.Label>
    <RadioGroup.Label.Input value="deep-dish" />
    <RadioGroup.Label.Text>Deep dish</RadioGroup.Label.Text>
  </RadioGroup.Label>
</RadioGroup>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<RadioGroup name"pizza-crust" value="deep-dish">
  <RadioGroup.Label>
    <RadioGroup.Label.Input value="deep-dish" />
    <RadioGroup.Label.Text>Deep dish</RadioGroup.Label.Text>
  </RadioGroup.Label>
</RadioGroup>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

useRadioInput

<RadioGroup name"pizza-crust" value="deep-dish">
  <RadioGroup.Label>
    <RadioGroup.Label.Input value="deep-dish" />
    <RadioGroup.Label.Text>Deep dish</RadioGroup.Label.Text>
  </RadioGroup.Label>
</RadioGroup>

Accessibility Guidelines

How Radio Buttons Impact the Accessible Experience

While associating labels to each radio button input is critical, radio buttons are used in groups of mutually exclusive choices. A group of choices requires context, such as, selecting your pizza crust. Designing a clear legend and building the context of the group is a key foundation for accessible radio buttons when users cannot visually perceive the layout.

Keyboard Interaction

Each Radio Button must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Radio Buttons must support the following keyboard interactions:

• Tab: focus the group of radio buttons
• Space: select focused radio button
• Down Arrow or Right Arrow: select the next radio button
• Up Arrow or Left Arrow: select the previous radio button

Screen Reader Interaction

Radio Buttons must communicate the following to users:

• The name (Form Field Label) of the radio button grouping
• The accessible name (label) of the focused radio button
• Which Radio Button in the group is selected
• The total number of radio buttons in the grouping

Design Annotations Needed

• Write the context (legend) of the radio button grouping.

Implementation Markup Needed

• Radio buttons must have a required attribute when the Radio Group is required for submission.
• Radio buttons must have an aria-invalid=”true” attribute when the Radio Group has an error condition.
• [Included in component] A <label> element is required with a for attribute referencing the unique id value of the associated radio button.
• [Included in component] A <fieldset> element establishes the group of related Radio Buttons. The child <legend> element describes the context of the grouping.
• [Included in component] A disabled attribute is set when the radio button is disabled.

Content Guidelines

• Form Field Labels are written in title case.
• The Radio Label for each individual selection are kept as concise as possible and written in sentence case.
• When writing Radio Button labels, refer to the Radio Buttons section of the Content Style Guide.