Radio

Radio Buttons allow a user to select one value from a predefined list of 7 or fewer options.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-react

Anatomy

Image of a Radio Group in its default state.

  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

Radio Buttons are intended to be grouped together using a Radio Group.

Radio Group should be used in tandem with Form Field where the useFieldset prop is set to true to meet accessibility standards.

Choose Your Pizza Crust

Disabled

Set the disabled prop of the Radio Button to prevent users from interacting with it.

Choose Your Pizza Crust

Radio Buttons with No Values

The value prop may be omitted from Radio Buttons, in which case the value prop of the Radio Group should be set using the zero-based index of the selected Radio Button.

Choose Your Pizza Crust

Value: 0

Ref Forwarding

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

Choose Your Pizza Crust

Label Position

Set the labelPosition prop of the wrapping Form Field to designate the position of the label relative to the Radio Group. labelPosition accepts the following values:

  • FormField.LabelPosition.Top (Default)
  • FormField.LabelPosition.Left
Choose Your Pizza Crust

Required

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

Choose Your Pizza Crust*

Error States

Set the error prop of the wrapping Form Field to FormField.ErrorType.Alert or FormField.ErrorType.Error to set the Radio Group to the Alert or Error state, respectively. You will also need to set the hintId and hintText props on the Form Field to meet accessibility standards.

Alert

Choose Your Pizza Crust

Alert: Deep Dish is no longer available. Please select a different crust.

Error

Choose Your Pizza Crust

Error: Deep Dish is no longer available. Please select a different crust.

Props

Radio Props

Undocumented props are spread to the underlying <input type="radio"> element.

NameTypeDefaultDescription
checkedboolean | undefinedfalseIf true, set the Radio button to the checked state.
disabledboolean | undefinedfalseIf true, set the Radio button to the disabled state.
idstring | undefinedA uniquely generated idThe HTML `id` of the underlying radio input element. This is required if `label` is defined as a non-empty string.
labelstring | undefined''The text of the Radio button label.
namestring | undefinedThe name of the Radio button.
onChange((e: ChangeEvent<HTMLInputElement>) => void) | undefinedThe function called when the Radio button state changes.
valuestring | undefinedThe value of the Radio button.
themeEmotionCanvasTheme | undefined
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

Radio Group Props

Undocumented props are spread to the outermost element rendered by Radio Group.

NameTypeDefaultDescription
valuestring | number | undefined0The selected value of the RadioGroup. If a string is provided, the Radio button with the corresponding value will be selected. If a number is provided, the Radio button with the corresponding index will be selected.
namestring | undefinedThe common `name` passed to all Radio button children of the RadioGroup. This enables you to avoid specifying the `name` for each child.
errorErrorType | undefinedThe type of error associated with the RadioGroup (if applicable).
onChange((value: string | number) => void) | undefinedThe function called when the RadioGroup state changes. The value passed to the callback function will be the value of the selected Radio button if it has one; otherwise, the index of the selected Radio button will be passed in.
themeEmotionCanvasTheme | undefined
growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.

Specifications

GivenWhenThen
given the 'Basic' story is rendered
    • it should not have any axe errors
    given the 'Basic' story is rendered
    • the "Gluten free" radio button is clicked
    • the "Gluten free" radio button should be checked
    given the 'Basic' story is rendered
    • clicking the "Gluten free" radio button and then clicking the "Thin" radio button
    • the "Gluten free" radio button should not be checked
    given the 'Basic' story is rendered
    • clicking the "Gluten free" radio button and then clicking the "Thin" radio button
    • the "Thin" radio button should be checked
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
      • the "Gluten free" radio button is clicked
      • the "Gluten free" radio button should be checked
      given the 'Alert' story is rendered
      • clicking the "Gluten free" radio button and then clicking the "Thin" radio button
      • the "Gluten free" radio button should not be checked
      given the 'Alert' story is rendered
      • clicking the "Gluten free" radio button and then clicking the "Thin" radio button
      • the "Thin" radio button should be checked
      given the 'Error' story is rendered
        • it should not have any axe errors
        given the 'Error' story is rendered
        • the "Gluten free" radio button is clicked
        • the "Gluten free" radio button should be checked
        given the 'Error' story is rendered
        • clicking the "Gluten free" radio button and then clicking the "Thin" radio button
        • the "Gluten free" radio button should not be checked
        given the 'Error' story is rendered
        • clicking the "Gluten free" radio button and then clicking the "Thin" radio button
        • the "Thin" radio button should be checked
        given the 'Disabled' story is rendered
          • it should not have any axe errors
          given the 'Disabled' story is rendered
            • the "Gluten free (sold out)" radio button should be disabled
            Source: Radio.spec.ts

            Accessibility Guidelines

            • The Form Field Label can be positioned in two places; above or left for LTR languages. Form Field Labels are aligned to the right for RTL languages.
            • Checkbox Labels are positioned to the right of Checkboxes for LTR languages or to the left of Checkboxes for RTL languages.
            • Radio Buttons must be in close proximity to their labels. This practice will benefit those who are using magnification software and may not be perceiving the entire page at one time.
            • Radio Button groups should be programmatically grouped together with an associated legend or description.

            Structure

            • <input> tag with attribute type="radio" to display a Radio Button.
            • <label> tag with attribute for="RadioBUttonID" to display a Radio Label.

            Visual

            • Avoid using color alone to differentiate between errors and alerts. Instead, use icons or text that says “Error” or “Alert.”
            • If both icons and visible text are used to differentiate between errors and alerts, the icons are considered redundant and should not provide any alternative text for screen readers.
            • When possible, error and alert states should provide information on how to fix issues or hints on fixing formatting.
            • Any Icon Buttons associated with a Checkbox must meet the Non-Text Contrast requirement.
            • Ensure Form Field Label and Checkbox Label exceeds a contrast ratio of 4.5:1 against the background to meet WCAG Success Criterion 1.4.3 for minimum contrast.
            • Ensure keyboard focus is visually indicated and exceeds a contrast ratio of 3.0:1 against the background and prior state to meet WCAG Success Criterion 1.4.11 for non-text contrast.

            Interaction

            • Clicking the Radio Button or Radio Label will select the option and unselect another option in the same group.

            Screen Reader

            • Form Field Labels are announced.
            • Radio Labels are announced.
            • Selected status of Radio Buttons are announced.

            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.

            Can't Find What You Need?

            Check out our FAQ section which may help you find the information you're looking for.

            FAQ Section