Skip to Content

Radio

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

Interaction Modes

Configuring

Reviewing

Selecting

Install

yarn add @workday/canvas-kit-preview-react

Component Type

Input

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.2.12

Experience Surfaces

Page Body Inline

Component Type

Input

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.2.12

Experience Surfaces

Page Body Inline

Radio (Preview) vs. Radio (Main)

We recommend you use the Radio component in the Preview package (@workday/canvas-kit-preview-react) documented here on this page. The Radio component in the Main package (@workday/canvas-kit-react) will eventually be replaced with the Radio component in the Preview package. See the Packages Glossary for what Preview means.

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

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.RadioButton 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 FormFieldGroup. FormFieldGroup.Label names the group, and FormFieldGroup.Input associates hint, error, and required state with each radio.

Choose Your Pizza Crust
Value selected: deep-dish
import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
import {Flex} from '@workday/canvas-kit-react/layout';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';

const formfieldInputStyles = createStyles({
  width: px2rem(200),
});

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  return (
    <Flex cs={{flexDirection: 'column'}}>
      <FormFieldGroup>
        <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
        <FormFieldGroup.Field>
          <FormFieldGroup.List
            cs={formfieldInputStyles}
            as={RadioGroup}
            name="pizza-crust"
            onChange={handleChange}
            value={value}
          >
            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
              Deep dish
            </FormFieldGroup.Input>
            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
              Thin
            </FormFieldGroup.Input>
            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
              Gluten free
            </FormFieldGroup.Input>
            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
              Cauliflower
            </FormFieldGroup.Input>
            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="custom">
              Butter - the best thing to put on bread
            </FormFieldGroup.Input>
          </FormFieldGroup.List>
        </FormFieldGroup.Field>
      </FormFieldGroup>
      Value selected: {value}
    </Flex>
  );
};

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

Inverse

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

import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {Box} from '@workday/canvas-kit-react/layout';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const styleOverrides = {
  containerStyles: createStyles({
    backgroundColor: system.color.surface.contrast.default,
    padding: system.padding.md,
  }),
  formFieldStyles: createStyles({
    legend: {
      color: system.color.fg.inverse,
    },
  }),
};

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  return (
    <Box cs={styleOverrides.containerStyles}>
      <RadioGroup name="crust-inverse" onChange={handleChange} value={value}>
        <RadioGroup.RadioButton variant="inverse" value="deep-dish">
          Deep dish
        </RadioGroup.RadioButton>
        <RadioGroup.RadioButton variant="inverse" value="thin">
          Thin
        </RadioGroup.RadioButton>
        <RadioGroup.RadioButton variant="inverse" value="gluten-free">
          Gluten free
        </RadioGroup.RadioButton>
        <RadioGroup.RadioButton variant="inverse" value="cauliflower">
          Cauliflower
        </RadioGroup.RadioButton>
      </RadioGroup>
    </Box>
  );
};

Radio Group with No Value

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

Choose Your Pizza Crust
import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>(0);

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };
  return (
    <FormFieldGroup>
      <FormFieldGroup.Label as="legend">Choose Your Pizza Crust</FormFieldGroup.Label>
      <FormFieldGroup.List
        as={RadioGroup}
        name="crust-no-value"
        onChange={handleChange}
        value={value}
      >
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
          Deep dish
        </FormFieldGroup.Input>
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
          Thin
        </FormFieldGroup.Input>
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
          Gluten free
        </FormFieldGroup.Input>
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
          Cauliflower
        </FormFieldGroup.Input>
      </FormFieldGroup.List>
    </FormFieldGroup>
  );
};

Ref Forwarding

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

Choose Your Pizza Crust
import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');
  const glutenFreeRef = React.useRef(null);

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  const handleClick = () => {
    glutenFreeRef.current.click();
  };

  return (
    <>
      <FormFieldGroup>
        <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
        <FormFieldGroup.List as={RadioGroup} name="crust-ref" onChange={handleChange} value={value}>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
            Deep dish
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
            Thin
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free" ref={glutenFreeRef}>
            Gluten free
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
            Cauliflower
          </FormFieldGroup.Input>
        </FormFieldGroup.List>
      </FormFieldGroup>
      <PrimaryButton onClick={handleClick}>Select Gluten Free</PrimaryButton>
    </>
  );
};

Label Position

Set the orientation prop of the Form Field to designate the position of the label relative to the input component. By default, the orientation will be set to vertical.

Choose Your Pizza Crust
import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };
  return (
    <FormFieldGroup orientation="horizontalStart">
      <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
      <FormFieldGroup.Field>
        <FormFieldGroup.List
          as={RadioGroup}
          name="crust-label"
          onChange={handleChange}
          value={value}
        >
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
            Deep dish
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
            Thin
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
            Gluten free
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
            Cauliflower
          </FormFieldGroup.Input>
        </FormFieldGroup.List>
      </FormFieldGroup.Field>
    </FormFieldGroup>
  );
};

Required

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

Choose Your Pizza Crust

You must choose a crust

import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>('');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };
  return (
    <FormFieldGroup isRequired={true}>
      <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
      <FormFieldGroup.List
        as={RadioGroup}
        name="crust-required"
        onChange={handleChange}
        value={value}
      >
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
          Deep dish
        </FormFieldGroup.Input>
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
          Thin
        </FormFieldGroup.Input>
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
          Gluten free
        </FormFieldGroup.Input>
        <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
          Cauliflower
        </FormFieldGroup.Input>
      </FormFieldGroup.List>
      <FormFieldGroup.Hint>You must choose a crust</FormFieldGroup.Hint>
    </FormFieldGroup>
  );
};

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.

Choose Your Pizza Crust
import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };
  return (
    <FormFieldGroup>
      <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
      <FormFieldGroup.Field>
        <FormFieldGroup.List
          as={RadioGroup}
          name="crust-disabled"
          onChange={handleChange}
          value={value}
        >
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
            Deep dish
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
            Thin
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} disabled value="gluten-free">
            Gluten free (sold out)
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
            Cauliflower
          </FormFieldGroup.Input>
        </FormFieldGroup.List>
      </FormFieldGroup.Field>
    </FormFieldGroup>
  );
};

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.

Choose Your Pizza Crust
Value selected: deep-dish
import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
import {Flex} from '@workday/canvas-kit-react/layout';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const styleOverrides = {
  formfieldInputStyles: createStyles({
    width: px2rem(200),
  }),
  radioGroupLabelTextStyles: createStyles({
    color: system.color.fg.default,
  }),
};

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  return (
    <Flex cs={{flexDirection: 'column'}}>
      <FormFieldGroup>
        <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
        <FormFieldGroup.Field>
          <FormFieldGroup.List
            as={RadioGroup}
            name="pizza-crust-custom"
            onChange={handleChange}
            cs={styleOverrides.formfieldInputStyles}
            value={value}
          >
            <RadioGroup.Label>
              <FormFieldGroup.Input as={RadioGroup.Label.Input} value="deep-dish" />
              <RadioGroup.Label.Text cs={styleOverrides.radioGroupLabelTextStyles}>
                Deep dish
              </RadioGroup.Label.Text>
            </RadioGroup.Label>
            <RadioGroup.Label>
              <FormFieldGroup.Input as={RadioGroup.Label.Input} value="gluten-free" />
              <RadioGroup.Label.Text cs={styleOverrides.radioGroupLabelTextStyles}>
                Gluten free
              </RadioGroup.Label.Text>
            </RadioGroup.Label>
            <RadioGroup.Label>
              <FormFieldGroup.Input as={RadioGroup.Label.Input} value="cauliflower" />
              <RadioGroup.Label.Text cs={styleOverrides.radioGroupLabelTextStyles}>
                Cauliflower
              </RadioGroup.Label.Text>
            </RadioGroup.Label>
          </FormFieldGroup.List>
        </FormFieldGroup.Field>
      </FormFieldGroup>
      Value selected: {value}
    </Flex>
  );
};

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.

Choose Your Pizza Crust
Value selected: deep-dish
import React from 'react';

import {StyledRadioButton} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
import {Flex} from '@workday/canvas-kit-react/layout';
import {px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  return (
    <Flex cs={{flexDirection: 'column'}}>
      <FormFieldGroup as="fieldset">
        <FormFieldGroup.Label as="legend">Choose Your Pizza Crust</FormFieldGroup.Label>
        <Flex cs={{gap: system.gap.xl}}>
          <Flex as="label" cs={{gap: px2rem(12)}}>
            <FormFieldGroup.Input
              as={StyledRadioButton}
              onChange={handleChange}
              value="deep-dish"
              name="pizza-crust-standalone"
              checked={value === 'deep-dish'}
            />
            Deep dish
          </Flex>
          <Flex as="label" cs={{gap: px2rem(12)}}>
            <FormFieldGroup.Input
              as={StyledRadioButton}
              onChange={handleChange}
              value="gluten-free"
              checked={value === 'gluten-free'}
              name="pizza-crust-standalone"
            />
            Gluten free
          </Flex>
        </Flex>
      </FormFieldGroup>
      Value selected: {value}
    </Flex>
  );
};

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 FormFieldGroup to "caution" or "error" to set the group to the alert or error state. Put the message in FormFieldGroup.Hint. FormFieldGroup.Input associates that text with each radio.

Caution

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

Choose Your Pizza Crust

Deep dish is an extra $2.99.

import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  return (
    <FormFieldGroup error="caution" id="hint-alert">
      <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
      <FormFieldGroup.Field>
        <FormFieldGroup.List
          as={RadioGroup}
          name="crust-alert"
          onChange={handleChange}
          value={value}
        >
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
            Deep dish
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
            Thin
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
            Gluten free
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
            Cauliflower
          </FormFieldGroup.Input>
        </FormFieldGroup.List>
        <FormFieldGroup.Hint>Deep dish is an extra $2.99.</FormFieldGroup.Hint>
      </FormFieldGroup.Field>
    </FormFieldGroup>
  );
};

Error

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

Choose Your Pizza Crust

Deep dish is currently sold out.

import React from 'react';

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [value, setValue] = React.useState<string | number>('deep-dish');

  const handleChange = (e: React.ChangeEvent) => {
    const target = e.currentTarget;
    if (target instanceof HTMLInputElement) {
      setValue(target.value);
    }
  };

  return (
    <FormFieldGroup error="error">
      <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
      <FormFieldGroup.Field>
        <FormFieldGroup.List
          as={RadioGroup}
          name="crust-error"
          onChange={handleChange}
          value={value}
        >
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
            Deep dish
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
            Thin
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
            Gluten free
          </FormFieldGroup.Input>
          <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
            Cauliflower
          </FormFieldGroup.Input>
        </FormFieldGroup.List>
        <FormFieldGroup.Hint>Deep dish is currently sold out.</FormFieldGroup.Hint>
      </FormFieldGroup.Field>
    </FormFieldGroup>
  );
};

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.

Custom Styles

Radio and its subcomponents support custom styling via the cs prop. For more information, check our “How To Customize Styles” .

Accessibility

The primary accessibility goal is to ensure users can identify the radio group and each option, determine which option is selected, and hear associated hints, errors, and required state when a radio receives focus. Use Radio when the user must choose one option from a list. For independent options, use Checkbox instead.

Minimum Accessible Structure

The following matches the Basic Example: a FormFieldGroup with FormFieldGroup.List as={RadioGroup}, and two or more FormFieldGroup.Input as={RadioGroup.RadioButton} options.

import {RadioGroup} from '@workday/canvas-kit-preview-react/radio'; import {FormFieldGroup} from '@workday/canvas-kit-react/form-field'; <FormFieldGroup> <FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label> <FormFieldGroup.Field> <FormFieldGroup.List as={RadioGroup}> <FormFieldGroup.Input as={RadioGroup.RadioButton}>Deep dish</FormFieldGroup.Input> <FormFieldGroup.Input as={RadioGroup.RadioButton}>Thin</FormFieldGroup.Input> </FormFieldGroup.List> </FormFieldGroup.Field> </FormFieldGroup>;

Each option needs visible text. See the Basic Example for selection behavior.

Built-in Behaviors

Canvas Kit applies these automatically when you compose FormFieldGroup with RadioGroup. Do not duplicate them in consuming code.

ARIA and DOM (applied by RadioGroup and FormFieldGroup):

  • RadioGroup: Renders a div. It does not set role="radiogroup".
  • RadioGroup.RadioButton: Renders a <label> around <input type="radio"> and the visible text. The wrapping <label> is the association, so an htmlFor pairing is not needed. That text is the option’s accessible name, and clicking it selects the radio.

Keyboard (native radio behavior):

RadioGroup uses native radio keyboard behavior. Tab moves to the selected radio, or to the first radio when none is selected, and then leaves the group. Arrow keys move and select within the group.

Screen reader expectations (when built-in behaviors are used as intended):

  • On focus, assistive technology announces the group name from FormFieldGroup.Label, along with the option name, radio role, and checked state.
  • When applicable, it also announces required state, invalid state (error="error"), and hint or error text. Caution does not set aria-invalid.
  • Disabled radios are announced as unavailable.

For group, hint, error, and required association, see FormField’s Built-in Behaviors.

Accessibility Requirements

Required in application code for an accessible Radio group. Rows marked (conditional) apply only when the situation matches—otherwise omit.

If no design spec is provided: use a visible FormFieldGroup.Label. On FormFieldGroup.List as={RadioGroup}, set a shared name and render two or more RadioGroup.RadioButton options with visible text and their own value. Omit error, isRequired, FormFieldGroup.Hint, disabled, aria-describedby on RadioGroup, error on RadioGroup, a ref, and StyledRadioButton unless the spec requires them.

Programmatic focus (conditional — omit by default):

Attach a ref only when the product must move focus to a radio after an action. Do not attach a ref or call focus() unless the design or developer asks for it. See Ref Forwarding.

RequirementHow to satisfy
Group and option namesUse FormFieldGroup with a visible FormFieldGroup.Label. Render FormFieldGroup.List as={RadioGroup} with a shared name, and give every FormFieldGroup.Input as={RadioGroup.RadioButton} visible text and its own value. The shared name groups the inputs, and each option value is what the selected state matches. See Basic Example.
Error state (conditional)When the selection is invalid, set error="error" on FormFieldGroup and prefix FormFieldGroup.Hint with “Error:”. See Error States.
Hint, caution, or required (conditional)On FormFieldGroup, use FormFieldGroup.Hint for hint text, error="caution" for caution, and isRequired for required state, only when the spec includes that state. See Required and FormField accessibility.
Disabled (conditional)Set disabled on an unavailable RadioGroup.RadioButton. Never disable the selected radio. See Disabled.

Summary for code generation:

  • REQUIRED: FormFieldGroup, visible FormFieldGroup.Label, FormFieldGroup.List as={RadioGroup} with a shared name, and two or more RadioGroup.RadioButton options, each with visible text and its own value
  • CONDITIONAL: when the selection is invalid, error="error" on FormFieldGroup and FormFieldGroup.Hint prefixed with “Error:”. Hint text, error="caution", and isRequired only when the spec includes that state. Also disabled (not on the selected radio). See FormField accessibility for group hint, caution, and required.

Anti-Patterns

Do not generate code that does the following (see Accessibility Requirements above for what to supply instead):

  • Add role="radiogroup" to RadioGroup — FormFieldGroup provides the group semantics
  • Manually set aria-checked, aria-invalid, aria-required, or aria-describedby — RadioGroup and FormFieldGroup.Input wire these attributes
  • Use FormField with useFieldset, or set hintId and hintText — group radios with FormFieldGroup and put the message in FormFieldGroup.Hint
  • Wrap radios in FormField.Input — use FormFieldGroup.Input as={RadioGroup.RadioButton}
  • Use StyledRadioButton unless the spec requires a radio outside RadioGroup. In that case supply accessible option and group names and the necessary behavior. See Standalone Radio Button
  • Intercept Tab or arrow keys — native radio behavior moves and selects within the group
  • Set disabled on the selected radio — that removes the group’s tab stop, so keyboard users cannot move within the group. See Disabled
  • Set error on RadioGroup — set it on FormFieldGroup so Canvas Kit provides both the visual and accessible error state. See Error States
  • Rely on color alone for an error or caution — include FormFieldGroup.Hint. Use error="error" when the selection is invalid so aria-invalid is set. See Error States

Component API

RadioGroup

Use RadioGroup to group a collection of RadioGroup.RadioButton components under a common name.

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

Layout Component

RadioGroup supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

Props extend from . If a model is passed, props from RadioModelConfig are ignored.

NameTypeDescriptionDefault
error

The type of error associated with the RadioGroup (if applicable).

theme
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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> )
childrenReactNode
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

div
refReact.Ref<R = div>

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).

model

Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.

elemPropsHook(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

RadioGroup.RadioButton

RadioGroup.RadioButton renders an <input type="radio" /> and its associated <label> (using children as the label's contents). This component should satisfy most use cases; use RadioGroup.Label and its sub components if you require more flexibility.

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

Layout Component

Radio supports all props from thelayout component.

Props

Props extend from input. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
childrenReactNode

The Radio input and label children of RadioLabel

theme
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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> )
disabled boolean | undefined
variant 'inverse' | undefined
value string | number
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

input
refReact.Ref<R = input>

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).

model

Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.

elemPropsHook(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

RadioGroup.Label

Use RadioGroup.Label instead of RadioGroup.Radio if you need direct access to the label and the radio input. This will render a <label> that wraps an <input type="radio" /> and a <span> for the label text.

<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>

Layout Component

Radio.Label supports all props from thelayout component.

Props

Props extend from label. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
childrenReactNode

The Radio input and label children of RadioLabel

theme
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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> )
disabled boolean | undefined
variant 'inverse' | undefined
value string | number
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

label
refReact.Ref<R = label>

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).

model

Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.

elemPropsHook(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

RadioGroup.Label.Input

Use RadioGroup.Label.Input within a RadioGroup.Label to render the input portion of a radio button.

<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>

Layout Component

RadioGroup.Label.Input supports all props from thelayout component.

Props

Props extend from input. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
childrenReactNode

The Radio input and label children of RadioLabel

theme
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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> )
disabled boolean | undefined
variant 'inverse' | undefined
value string | number
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

input
refReact.Ref<R = input>

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).

model

Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.

elemPropsHook(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useRadioInput

Basic type information:

useRadioInput

RadioGroup.Label.Text

Use RadioGroup.Label.Text within a RadioGroup.Label to render the label text portion of a radio button.

<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>

Props

Props extend from span. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
model

Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.

elemPropsHook(
  model: ,
  elemProps: TProps
) => HTML Attributes

Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

Model

useRadioModel

useRadioModel (config: ):

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.