RadioGroup

RadioGroups are used for selecting only 1 item from a list of 2 or more items. If you need multiple selection or have only one option, use Checkbox. If you need to provide a binary on/off choice that takes effect immediately, use Switch.

also known as Single Select, Option Buttons, Radio Inputs

Figma:

Partially ready

Web:

iOS:

Android:

A11y:

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();

  return (
    <RadioGroup legend="Gender" id="header-example">
      <RadioGroup.RadioButton
        checked={favorite === 'Female'}
        id="genderFemale"
        label="Female"
        name="gender-pref"
        onChange={() => setFavorite('Female')}
        value="Female"
      />
      <RadioGroup.RadioButton
        checked={favorite === 'Male'}
        id="genderMale"
        label="Male"
        name="gender-pref"
        onChange={() => setFavorite('Male')}
        value="Male"
      />
      <RadioGroup.RadioButton
        checked={favorite === 'Non-binary'}
        id="genderNon-binary"
        label="Non-binary"
        name="gender-pref"
        onChange={() => setFavorite('Non-binary')}
        value="Non-binary"
      />
      <RadioGroup.RadioButton
        checked={favorite === 'Prefer not to state'}
        id="genderPrefer not to state"
        label="Prefer not to state"
        name="gender-pref"
        onChange={() => setFavorite('Prefer not to state')}
        value="Prefer not to state"
      />
    </RadioGroup>
  );
}

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();

  return (
    <RadioGroup legend="Gender" id="header-example">
      <RadioGroup.RadioButton
        checked={favorite === 'Female'}
        id="genderFemale"
        label="Female"
        name="gender-pref"
        onChange={() => setFavorite('Female')}
        value="Female"
      />
      <RadioGroup.RadioButton
        checked={favorite === 'Male'}
        id="genderMale"
        label="Male"
        name="gender-pref"
        onChange={() => setFavorite('Male')}
        value="Male"
      />
      <RadioGroup.RadioButton
        checked={favorite === 'Non-binary'}
        id="genderNon-binary"
        label="Non-binary"
        name="gender-pref"
        onChange={() => setFavorite('Non-binary')}
        value="Non-binary"
      />
      <RadioGroup.RadioButton
        checked={favorite === 'Prefer not to state'}
        id="genderPrefer not to state"
        label="Prefer not to state"
        name="gender-pref"
        onChange={() => setFavorite('Prefer not to state')}
        value="Prefer not to state"
      />
    </RadioGroup>
  );
}

Props

Component props
Name	Type	Default
`children` Required	`React.Node`	-
	A collection of RadioGroup.RadioButtons representing the available options, as well as any Labels or layout components (Box, Flex, etc.), if needed. Other components such as Checkboxes should not be included. Note that children can be grouped into organizational components if desired.
`id` Required	`string`	-
	A unique identifier for this RadioGroup.
`legend` Required	`string`	-
	The description of the radio group that tells users what is being asked of them.
`direction`	`"column" \| "row"`	-
	Determines the layout of the group. See the direction variant to learn more.
`errorMessage`	`string`	-
	Adds an error message below the group of radio buttons. See the error variant to learn more.
`legendDisplay`	`"visible" \| "hidden"`	-
	Whether the legend should be visible or not. If hidden, the legend is still available for screen reader users, but does not appear visually. See the legend visibility variant to learn more.

Subcomponents

RadioGroup.RadioButton

Use RadioGroup.RadioButtons to present an option for selection to the user within a RadioGroup. They should not be used outside of RadioGroup or when the user can select more than one option from a list.

RadioGroup.RadioButton Props

RadioGroup.RadioButton subcomponent props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the input.
`onChange` Required	`({\| event: SyntheticInputEvent<HTMLInputElement>, checked: boolean \|}) => void`	-
	Callback triggered when the user interacts with the input.
`value` Required	`string`	-
	The value of the input.
`checked`	`boolean`	-
	Indicates if the input is checked. See the state example for more details.
`disabled`	`boolean`	-
	Indicates if the input is disabled. See the state example for more details.
`helperText`	`string`	-
	Optional description for the input, used to provide more detail about an option. See the helperText example for more details.
`image`	`React.Node`	-
	An optional Image component can be supplied to add an image to each radio button. Spacing is already accounted for — simply specify the width and height. See the images example for more details.
`label`	`string`	-
	The displayed label for the input.
`name`	`string`	-
	The name given for all radio buttons in a single group.
`ref`	`HTMLInputElement`	-
	Ref forwarded to the underlying input element. See ref example for more details.
`size`	`"sm" \| "md"`	-
	sm: 16px, md: 24px

Usage guidelines

When to use

In a list, form or table, to present users with multiple, related options where only one option can be selected.
When selection doesn’t take immediate effect and requires form submission.

When not to use

Situations where users can select multiple options. Use Checkbox instead.
When there is only one item to select or deselect. Use Checkbox instead.
When a selection takes immediate effect, especially on mobile. Use Switch instead.
When it is visually difficult to observe that RadioGroup turns something on or off. Use Switch instead.

Best Practices

Use RadioGroup to select only one option from a list of 2 or more items.

Don't

Use RadioGroup to select multiple items.

Keep labels and legends clear and brief to avoid too many lines of text that are hard to scan and slow the user down. If clarification is needed, use IconButtons with Tooltips or helperText.

Don't

Use lengthy text that truncates and doesn’t offer clear instructions for how to make a selection.

Use RadioGroup when you need a clear answer to a binary question that requires form submission.

Don't

Use a RadioGroup to turn a state on and off with immediate effect on mobile; use Switch instead.

Accessibility

Ready

Labels

Each RadioButton in a RadioGroup should have a label that can be read by screen readers, and that can be clicked or tapped to make it easier for users to select and deselect options. Therefore, make sure to supply the label prop. If that’s not possible, make sure your standalone Label has an htmlFor prop that matches the id of the RadioButton. Test that a RadioButton and label are properly connected by clicking or tapping on the label and confirming that it activates the RadioButton next to it.

Legends

Each RadioGroup should have a legend that clearly delineates what is being chosen. If you cannot use the provided legend styling, legendDisplay can be set to hidden, and an alternative legend can be displayed. See the legend visibility variant for an example.

Keyboard interaction

After focus has been set on the first RadioButton inside a RadioGroup, the arrow keys are used to cycle focus between the various options. Clicking or tapping the label of RadioButton should also focus that particular RadioButton. All RadioGroup.RadioButtons within a RadioGroup should share the same name to ensure keyboard accessibility, but that name needs to be unique from other RadioGroup buttons on the page.

Localization

Be sure to localize errorMessage, helperText, label, and legend. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.

Variants

Direction

RadioGroups can be shown in a column or row by specifying the direction property.

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();
  const [favoriteFood, setFavoriteFood] = React.useState();

  return (
    <Flex gap={8} wrap>
      <RadioGroup legend="What is your favorite pet?" id="directionExample-1">
        <RadioGroup.RadioButton
          checked={favorite === 'dogs'}
          id="favoriteDog"
          label="Dogs"
          name="favorite"
          onChange={() => setFavorite('dogs')}
          value="dogs"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'cats'}
          id="favoriteCat"
          label="Cats"
          name="favorite"
          onChange={() => setFavorite('cats')}
          value="cats"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'plants'}
          id="favoritePlants"
          label="Plants"
          name="favorite"
          onChange={() => setFavorite('plants')}
          value="plants"
        />
      </RadioGroup>

      <RadioGroup legend="What is your favorite snack?" errorMessage="Please select one" direction="row" id="directionExample">
        <RadioGroup.RadioButton
          checked={favoriteFood === 'pizza'}
          id="favoritePizza"
          label="Pizza"
          name="favoriteFood"
          onChange={() => setFavoriteFood('pizza')}
          value="pizza"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'curry'}
          id="favoriteCurry"
          label="Curry"
          name="favoriteFood"
          onChange={() => setFavoriteFood('curry')}
          value="curry"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'sushi'}
          id="favoriteSushi"
          label="Sushi"
          name="favoriteFood"
          onChange={() => setFavoriteFood('sushi')}
          value="sushi"
        />
      </RadioGroup>
    </Flex>
  );
}

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();
  const [favoriteFood, setFavoriteFood] = React.useState();

  return (
    <Flex gap={8} wrap>
      <RadioGroup legend="What is your favorite pet?" id="directionExample-1">
        <RadioGroup.RadioButton
          checked={favorite === 'dogs'}
          id="favoriteDog"
          label="Dogs"
          name="favorite"
          onChange={() => setFavorite('dogs')}
          value="dogs"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'cats'}
          id="favoriteCat"
          label="Cats"
          name="favorite"
          onChange={() => setFavorite('cats')}
          value="cats"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'plants'}
          id="favoritePlants"
          label="Plants"
          name="favorite"
          onChange={() => setFavorite('plants')}
          value="plants"
        />
      </RadioGroup>

      <RadioGroup legend="What is your favorite snack?" errorMessage="Please select one" direction="row" id="directionExample">
        <RadioGroup.RadioButton
          checked={favoriteFood === 'pizza'}
          id="favoritePizza"
          label="Pizza"
          name="favoriteFood"
          onChange={() => setFavoriteFood('pizza')}
          value="pizza"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'curry'}
          id="favoriteCurry"
          label="Curry"
          name="favoriteFood"
          onChange={() => setFavoriteFood('curry')}
          value="curry"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'sushi'}
          id="favoriteSushi"
          label="Sushi"
          name="favoriteFood"
          onChange={() => setFavoriteFood('sushi')}
          value="sushi"
        />
      </RadioGroup>
    </Flex>
  );
}

Size

RadioButtons can be either sm (16px) or md (24px), which is the default.

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();
  const [favoriteFood, setFavoriteFood] = React.useState();

  return (
    <Flex gap={{ column: 0, row: 8 }}>
      <RadioGroup legend="What is your favorite snack?" errorMessage="Please select one" id="sizeExample">
        <RadioGroup.RadioButton
          checked={favorite === 'pizza'}
          id="favoriteSizePizzaSm"
          label="Pizza"
          name="favoriteFoodSm"
          onChange={() => setFavorite('pizza')}
          value="pizza"
          size="sm"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'curry'}
          id="favoriteSizeCurrySm"
          label="Curry"
          name="favoriteFoodSm"
          onChange={() => setFavorite('curry')}
          value="curry"
          size="sm"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'sushi'}
          id="favoriteSizeSushiSm"
          label="Sushi"
          name="favoriteFoodSm"
          onChange={() => setFavorite('sushi')}
          value="sushi"
          size="sm"
        />
      </RadioGroup>

      <RadioGroup legend="What is your favorite snack?" errorMessage="Please select one" id="sizeExampleMd">
        <RadioGroup.RadioButton
          checked={favoriteFood === 'pizza'}
          id="favoriteSizePizza"
          label="Pizza"
          name="favoriteFood-size"
          onChange={() => setFavoriteFood('pizza')}
          value="pizza"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'curry'}
          id="favoriteSizeCurry"
          label="Curry"
          name="favoriteFood-size"
          onChange={() => setFavoriteFood('curry')}
          value="curry"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'sushi'}
          id="favoriteSizeSushi"
          label="Sushi"
          name="favoriteFood-size"
          onChange={() => setFavoriteFood('sushi')}
          value="sushi"
        />
      </RadioGroup>
    </Flex>
  );
}

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();
  const [favoriteFood, setFavoriteFood] = React.useState();

  return (
    <Flex gap={{ column: 0, row: 8 }}>
      <RadioGroup legend="What is your favorite snack?" errorMessage="Please select one" id="sizeExample">
        <RadioGroup.RadioButton
          checked={favorite === 'pizza'}
          id="favoriteSizePizzaSm"
          label="Pizza"
          name="favoriteFoodSm"
          onChange={() => setFavorite('pizza')}
          value="pizza"
          size="sm"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'curry'}
          id="favoriteSizeCurrySm"
          label="Curry"
          name="favoriteFoodSm"
          onChange={() => setFavorite('curry')}
          value="curry"
          size="sm"
        />
        <RadioGroup.RadioButton
          checked={favorite === 'sushi'}
          id="favoriteSizeSushiSm"
          label="Sushi"
          name="favoriteFoodSm"
          onChange={() => setFavorite('sushi')}
          value="sushi"
          size="sm"
        />
      </RadioGroup>

      <RadioGroup legend="What is your favorite snack?" errorMessage="Please select one" id="sizeExampleMd">
        <RadioGroup.RadioButton
          checked={favoriteFood === 'pizza'}
          id="favoriteSizePizza"
          label="Pizza"
          name="favoriteFood-size"
          onChange={() => setFavoriteFood('pizza')}
          value="pizza"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'curry'}
          id="favoriteSizeCurry"
          label="Curry"
          name="favoriteFood-size"
          onChange={() => setFavoriteFood('curry')}
          value="curry"
        />
        <RadioGroup.RadioButton
          checked={favoriteFood === 'sushi'}
          id="favoriteSizeSushi"
          label="Sushi"
          name="favoriteFood-size"
          onChange={() => setFavoriteFood('sushi')}
          value="sushi"
        />
      </RadioGroup>
    </Flex>
  );
}

States

Disabled RadioButtons cannot be accessed by the keyboard and therefore should not contain any necessary info to complete the choice presented.

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();

  return (
      <RadioGroup legend="Which state is your favorite?" id="rowExample">
        <RadioGroup.RadioButton
          checked={false}
          id="unchecked"
          label="Unchecked"
          name="stateExample"
          onChange={() => setFavorite('unchecked')}
          value="unchecked"
        />
        <RadioGroup.RadioButton
          checked={true}
          id="checked"
          label="Checked"
          name="stateExample"
          onChange={() => setFavorite('checked')}
          value="checked"
        />
        <RadioGroup.RadioButton
          checked={false}
          id="uncheckedDisabled"
          label="Unchecked and disabled"
          name="stateExample"
          onChange={() => setFavorite('uncheckedDisabled')}
          value="uncheckedDisabled"
          disabled
        />
        <RadioGroup.RadioButton
          checked={true}
          id="checkedDisabled"
          label="Checked and disabled"
          name="stateExample"
          onChange={() => setFavorite('checkedDisabled')}
          value="checkedDisabled"
          disabled
        />
      </RadioGroup>
  );
}

function RadioButtonExample() {
  const [favorite, setFavorite] = React.useState();

  return (
      <RadioGroup legend="Which state is your favorite?" id="rowExample">
        <RadioGroup.RadioButton
          checked={false}
          id="unchecked"
          label="Unchecked"
          name="stateExample"
          onChange={() => setFavorite('unchecked')}
          value="unchecked"
        />
        <RadioGroup.RadioButton
          checked={true}
          id="checked"
          label="Checked"
          name="stateExample"
          onChange={() => setFavorite('checked')}
          value="checked"
        />
        <RadioGroup.RadioButton
          checked={false}
          id="uncheckedDisabled"
          label="Unchecked and disabled"
          name="stateExample"
          onChange={() => setFavorite('uncheckedDisabled')}
          value="uncheckedDisabled"
          disabled
        />
        <RadioGroup.RadioButton
          checked={true}
          id="checkedDisabled"
          label="Checked and disabled"
          name="stateExample"
          onChange={() => setFavorite('checkedDisabled')}
          value="checkedDisabled"
          disabled
        />
      </RadioGroup>
  );
}

With helperText

Use helperText to provide extra context or information for each option.

function RadioButtonExample() {
  const [availability, setAvailability] = React.useState();

  return (
    <RadioGroup legend="Which time slot works best for you?" id="helperTextExample">
        <RadioGroup.RadioButton
          checked={availability === 'monday'}
          id="monday"
          label="Monday"
          helperText="Morning and afternoon"
          name="Availability"
          onChange={() => setAvailability('monday')}
          value="monday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'tuesday'}
          id="tuesday"
          label="Tuesday"
          helperText="Morning, afternoon, and evening"
          name="Availability"
          onChange={() => setAvailability('tuesday')}
          value="tuesday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'wednesday'}
          id="Wednesday"
          label="Wednesday"
          helperText="Evening only"
          name="Availability"
          onChange={() => setAvailability('wednesday')}
          value="wednesday"
        />
    </RadioGroup>
  );
}

function RadioButtonExample() {
  const [availability, setAvailability] = React.useState();

  return (
    <RadioGroup legend="Which time slot works best for you?" id="helperTextExample">
        <RadioGroup.RadioButton
          checked={availability === 'monday'}
          id="monday"
          label="Monday"
          helperText="Morning and afternoon"
          name="Availability"
          onChange={() => setAvailability('monday')}
          value="monday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'tuesday'}
          id="tuesday"
          label="Tuesday"
          helperText="Morning, afternoon, and evening"
          name="Availability"
          onChange={() => setAvailability('tuesday')}
          value="tuesday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'wednesday'}
          id="Wednesday"
          label="Wednesday"
          helperText="Evening only"
          name="Availability"
          onChange={() => setAvailability('wednesday')}
          value="wednesday"
        />
    </RadioGroup>
  );
}

With Image

When including images, you can use the helperText property to clearly describe the information being presented by the image, or use the image's alt text to provide more context.

function RadioButtonExample() {
  const [artPreference, setArtPreference] = React.useState();

  return (
    <RadioGroup legend="Pick a placeholder image" id="imageExample">
      <RadioGroup.RadioButton
        checked={artPreference === 'coral'}
        id="coral"
        label="Coral"
        helperText="Botanical art in coral and green"
        image={<Box height={100} width={80}><Image alt="Botanical art in coral and green" src="https://i.ibb.co/7bQQYkX/stock2.jpg" fit="cover" naturalWidth={1} naturalHeight={1}/></Box>}

        name="Art Preference"
        onChange={() => setArtPreference('coral')}
        value="coral"
      />
      <RadioGroup.RadioButton
        checked={artPreference === 'blue'}
        id="blue"
        label="Blue"
        helperText="Typography and shoe in blue"
        image={<Box height={100} width={80}><Image alt="Typography and shoe in blue" src="https://i.ibb.co/jVR29XV/stock5.jpg" fit="cover" naturalWidth={1} naturalHeight={1}/></Box>}
        name="Art Preference"
        onChange={() => setArtPreference('blue')}
        value="blue"
      />
      <RadioGroup.RadioButton
        checked={artPreference === 'green'}
        id="green"
        label="Green"
        helperText="Abstract art in green"
        image={<Box height={100} width={80}><Image alt="Abstract art in green" src="https://i.ibb.co/FY2MKr5/stock6.jpg" fit="cover" naturalWidth={1} naturalHeight={1}/></Box>}
        name="Art Preference"
        onChange={() => setArtPreference('green')}
        value="green"
      />
    </RadioGroup>
  );
}

function RadioButtonExample() {
  const [artPreference, setArtPreference] = React.useState();

  return (
    <RadioGroup legend="Pick a placeholder image" id="imageExample">
      <RadioGroup.RadioButton
        checked={artPreference === 'coral'}
        id="coral"
        label="Coral"
        helperText="Botanical art in coral and green"
        image={<Box height={100} width={80}><Image alt="Botanical art in coral and green" src="https://i.ibb.co/7bQQYkX/stock2.jpg" fit="cover" naturalWidth={1} naturalHeight={1}/></Box>}

        name="Art Preference"
        onChange={() => setArtPreference('coral')}
        value="coral"
      />
      <RadioGroup.RadioButton
        checked={artPreference === 'blue'}
        id="blue"
        label="Blue"
        helperText="Typography and shoe in blue"
        image={<Box height={100} width={80}><Image alt="Typography and shoe in blue" src="https://i.ibb.co/jVR29XV/stock5.jpg" fit="cover" naturalWidth={1} naturalHeight={1}/></Box>}
        name="Art Preference"
        onChange={() => setArtPreference('blue')}
        value="blue"
      />
      <RadioGroup.RadioButton
        checked={artPreference === 'green'}
        id="green"
        label="Green"
        helperText="Abstract art in green"
        image={<Box height={100} width={80}><Image alt="Abstract art in green" src="https://i.ibb.co/FY2MKr5/stock6.jpg" fit="cover" naturalWidth={1} naturalHeight={1}/></Box>}
        name="Art Preference"
        onChange={() => setArtPreference('green')}
        value="green"
      />
    </RadioGroup>
  );
}

With an error

Use errorMessage to show an error message below the radio options.

function RadioButtonExample() {
  const [availability, setAvailability] = React.useState();

  return (
    <RadioGroup legend="Which time slot works best for you?" errorMessage="Please select one" id="VariantWithErrorMessage">
        <RadioGroup.RadioButton
          checked={availability === 'monday'}
          id="mondayError"
          label="Monday"
          helperText="Morning and afternoon"
          name="Availability with error"
          onChange={() => setAvailability('monday')}
          value="monday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'tuesday'}
          id="tuesdayError"
          label="Tuesday"
          helperText="Morning, afternoon, and evening"
          name="Availability with error"
          onChange={() => setAvailability('tuesday')}
          value="tuesday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'wednesday'}
          id="WednesdayError"
          label="Wednesday"
          helperText="Evening only"
          name="Availability with error"
          onChange={() => setAvailability('wednesday')}
          value="wednesday"
        />
    </RadioGroup>
  );
}

function RadioButtonExample() {
  const [availability, setAvailability] = React.useState();

  return (
    <RadioGroup legend="Which time slot works best for you?" errorMessage="Please select one" id="VariantWithErrorMessage">
        <RadioGroup.RadioButton
          checked={availability === 'monday'}
          id="mondayError"
          label="Monday"
          helperText="Morning and afternoon"
          name="Availability with error"
          onChange={() => setAvailability('monday')}
          value="monday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'tuesday'}
          id="tuesdayError"
          label="Tuesday"
          helperText="Morning, afternoon, and evening"
          name="Availability with error"
          onChange={() => setAvailability('tuesday')}
          value="tuesday"
        />
        <RadioGroup.RadioButton
          checked={availability === 'wednesday'}
          id="WednesdayError"
          label="Wednesday"
          helperText="Evening only"
          name="Availability with error"
          onChange={() => setAvailability('wednesday')}
          value="wednesday"
        />
    </RadioGroup>
  );
}

With custom labels

The label on RadioGroup.RadioButton can be replaced with a custom Label, as demonstrated below. Ensure the htmlFor property matches the id on the RadioButton.

function RadioButtonExample() {
          const [favorite, setFavorite] = React.useState();

          return (
              <RadioGroup legend="Campaign budget" id="bestPracticeBudget">
                <Flex gap={{ row: 2, column: 0 }} alignItems="center">
                  <RadioGroup.RadioButton
                    checked={favorite === "daily"}
                    id="daily-label-ex-custom"
                    name="budget-custom-label"
                    onChange={() => setFavorite('daily')}
                    value="daily"
                  />
                  <Label htmlFor="daily-label-ex-custom">
                    <Flex alignItems="center">
                      <Text>Daily</Text>
                      <IconButton size="sm" icon="info-circle" iconColor="gray" accessibilityLabel="info" tooltip={{text: "Sets a cap for the amount your campaign can spend each day"}}/>
                    </Flex>
                  </Label>
                </Flex>
                <Flex gap={{ row: 2, column: 0 }} alignItems="center">
                  <RadioGroup.RadioButton
                    checked={favorite === "lifetime"}
                    id="lifetime-label-ex-custom"
                    name="budget-custom-label"
                    onChange={() => setFavorite('lifetime')}
                    value="lifetime"
                  />
                  <Label htmlFor="lifetime-label-ex-custom">
                    <Flex alignItems="center">
                      <Text>Lifetime</Text>
                      <IconButton size="sm" icon="info-circle" iconColor="gray" accessibilityLabel="info" tooltip={{text: "Sets a cap for the amount your campaign can spend over the course of its lifetime"}}/>
                    </Flex>
                  </Label>
                </Flex>
              </RadioGroup>
          );
        }

function RadioButtonExample() {
          const [favorite, setFavorite] = React.useState();

          return (
              <RadioGroup legend="Campaign budget" id="bestPracticeBudget">
                <Flex gap={{ row: 2, column: 0 }} alignItems="center">
                  <RadioGroup.RadioButton
                    checked={favorite === "daily"}
                    id="daily-label-ex-custom"
                    name="budget-custom-label"
                    onChange={() => setFavorite('daily')}
                    value="daily"
                  />
                  <Label htmlFor="daily-label-ex-custom">
                    <Flex alignItems="center">
                      <Text>Daily</Text>
                      <IconButton size="sm" icon="info-circle" iconColor="gray" accessibilityLabel="info" tooltip={{text: "Sets a cap for the amount your campaign can spend each day"}}/>
                    </Flex>
                  </Label>
                </Flex>
                <Flex gap={{ row: 2, column: 0 }} alignItems="center">
                  <RadioGroup.RadioButton
                    checked={favorite === "lifetime"}
                    id="lifetime-label-ex-custom"
                    name="budget-custom-label"
                    onChange={() => setFavorite('lifetime')}
                    value="lifetime"
                  />
                  <Label htmlFor="lifetime-label-ex-custom">
                    <Flex alignItems="center">
                      <Text>Lifetime</Text>
                      <IconButton size="sm" icon="info-circle" iconColor="gray" accessibilityLabel="info" tooltip={{text: "Sets a cap for the amount your campaign can spend over the course of its lifetime"}}/>
                    </Flex>
                  </Label>
                </Flex>
              </RadioGroup>
          );
        }

Legend visibility

By default, the legend is visible above the items in the RadioGroup. However, if the form items are labeled by content elsewhere on the page, or a more complex legend is needed, the legendDisplay prop can be used to visually hide the legend. In this case, it is still available to screen reader users, but will not appear visually on the screen.

In the example below, the "Primary company account goal" text is acting as a heading and a legend for the radio buttons, so instead of repeating another legend, we visually hide the RadioGroup legend. When a user focuses on the first radio, a screen reader will announce "Sell more products, radio button, 1 of 3, Primary company account goal, group".

function RadioButtonExample() {
  const [goal, setGoal] = React.useState();

  return (
    <Flex direction="column" gap={{ column: 4, row: 0 }}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Heading size="400">Primary company account goal</Heading>
        <Text size="200">
          Choose your primary goal for this account to help us better understand your needs
          <Text inline size="200" weight="bold">
            <Link inline target="blank" href="https://www.pinterest.com/">
              Additional information
            </Link>
          </Text>
        </Text>
      </Flex>
      <RadioGroup legend="Primary company account goal" legendDisplay="hidden" id="legendExample">
        <RadioGroup.RadioButton
          checked={goal === "sell"}
          id="sell"
          label="Sell more products"
          name="account goals"
          onChange={() => setGoal('sell')}
          value="sell"
        />
        <RadioGroup.RadioButton
          checked={goal === "leads"}
          id="leads"
          label="Generate more leads for the company"
          name="account goals"
          onChange={() => setGoal('leads')}
          value="leads"
        />
        <RadioGroup.RadioButton
          checked={goal === "interest"}
          id="interest"
          label="Create content on Pinterest to attract an audience"
          name="account goals"
          onChange={() => setGoal('interest')}
          value="interest"
        />
      </RadioGroup>
    </Flex>
  );
}

function RadioButtonExample() {
  const [goal, setGoal] = React.useState();

  return (
    <Flex direction="column" gap={{ column: 4, row: 0 }}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Heading size="400">Primary company account goal</Heading>
        <Text size="200">
          Choose your primary goal for this account to help us better understand your needs
          <Text inline size="200" weight="bold">
            <Link inline target="blank" href="https://www.pinterest.com/">
              Additional information
            </Link>
          </Text>
        </Text>
      </Flex>
      <RadioGroup legend="Primary company account goal" legendDisplay="hidden" id="legendExample">
        <RadioGroup.RadioButton
          checked={goal === "sell"}
          id="sell"
          label="Sell more products"
          name="account goals"
          onChange={() => setGoal('sell')}
          value="sell"
        />
        <RadioGroup.RadioButton
          checked={goal === "leads"}
          id="leads"
          label="Generate more leads for the company"
          name="account goals"
          onChange={() => setGoal('leads')}
          value="leads"
        />
        <RadioGroup.RadioButton
          checked={goal === "interest"}
          id="interest"
          label="Create content on Pinterest to attract an audience"
          name="account goals"
          onChange={() => setGoal('interest')}
          value="interest"
        />
      </RadioGroup>
    </Flex>
  );
}

RadioButton with an anchor ref to a Popover component doesn't pass the correct positioning to the Popover. Instead set the anchor ref to the parent container.

function RadioButtonPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const [option, setOption] = React.useState(false);
  const anchorCatRef = React.useRef();
  const anchorDogRef = React.useRef();

  return (
    <RadioGroup legend="Tell us about yourself" id="popoverExample">
      <Box display="inlineBlock" ref={anchorCatRef}>
        <RadioGroup.RadioButton
          id="cat"
          checked={option === "cat"}
          label="I'm a cat person"
          onChange={() => {
            setOpen(true)
            setOption("cat")}
          }
          value="cat"
        />
      </Box>
      <Box display="inlineBlock" ref={anchorDogRef}>
        <RadioGroup.RadioButton
          id="dog"
          checked={option === "dog"}
          label="I'm a dog person"
          onChange={() => {
            setOpen(true)
            setOption('dog')}
          }
          value="dog"
        />
      </Box>
      {open &&
        <Layer>
          <Popover
            anchor={option === "cat" ? anchorCatRef.current  : anchorDogRef.current}
            idealDirection="right"
            onDismiss={() => setOpen(false)}
            positionRelativeToAnchor={false}
            shouldFocus={false}
            size="md"
          >
            <Box padding={3}>
              <Text
                color="default"
              >
                <Link
                  href={
                    option === "cat"
                      ? "https://www.pinterest.com/search/pins/?q=cats"
                      : "https://www.pinterest.com/search/pins/?q=dogs"
                  }
                  target='blank'
                  underline="always"
                >
                  { option === "cat"
                      ? "Check out cats on Pinterest!"
                      : "Check out dogs on Pinterest!"
                  }
                </Link>
              </Text>
            </Box>
          </Popover>
        </Layer>
      }
    </RadioGroup>
  );
}

function RadioButtonPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const [option, setOption] = React.useState(false);
  const anchorCatRef = React.useRef();
  const anchorDogRef = React.useRef();

  return (
    <RadioGroup legend="Tell us about yourself" id="popoverExample">
      <Box display="inlineBlock" ref={anchorCatRef}>
        <RadioGroup.RadioButton
          id="cat"
          checked={option === "cat"}
          label="I'm a cat person"
          onChange={() => {
            setOpen(true)
            setOption("cat")}
          }
          value="cat"
        />
      </Box>
      <Box display="inlineBlock" ref={anchorDogRef}>
        <RadioGroup.RadioButton
          id="dog"
          checked={option === "dog"}
          label="I'm a dog person"
          onChange={() => {
            setOpen(true)
            setOption('dog')}
          }
          value="dog"
        />
      </Box>
      {open &&
        <Layer>
          <Popover
            anchor={option === "cat" ? anchorCatRef.current  : anchorDogRef.current}
            idealDirection="right"
            onDismiss={() => setOpen(false)}
            positionRelativeToAnchor={false}
            shouldFocus={false}
            size="md"
          >
            <Box padding={3}>
              <Text
                color="default"
              >
                <Link
                  href={
                    option === "cat"
                      ? "https://www.pinterest.com/search/pins/?q=cats"
                      : "https://www.pinterest.com/search/pins/?q=dogs"
                  }
                  target='blank'
                  underline="always"
                >
                  { option === "cat"
                      ? "Check out cats on Pinterest!"
                      : "Check out dogs on Pinterest!"
                  }
                </Link>
              </Text>
            </Box>
          </Popover>
        </Layer>
      }
    </RadioGroup>
  );
}

Writing

Be brief with RadioGroup button labels so they are easily scanned.
Error messages should be simple, clear and direct without negative, overly clever and technical language.
A good error message: “To continue you must select one item from this list.”

Don't

Include lengthy text labels that make it hard for a user to scan a list of choices.
Write error messages that are overly-technical, long, negative, and too clever.
A not-so-great error message: “Hey there, nice try, but not selecting something is baaaad. Bad as in bad. Per error code i-five, you must select a choice from this boolean”.

CheckBox
Use when presenting a user with a list of choices where multiple options can be selected.

Switch
Use for single-cell options that can be turned on or off. Examples include a list of settings that take effect immediately without having to confirm form submission.

Fieldset
Fieldset is used under the hood of RadioGroup to ensure accessible groups of radio buttons.

Edit page on GitHub

; Opens a new tab

RadioGroup

also known as Single Select, Option Buttons, Radio Inputs

Props

Subcomponents

RadioGroup.RadioButton

RadioGroup.RadioButton Props

Usage guidelines

Best Practices

Accessibility

Labels

Legends

Keyboard interaction

Localization

Variants

Direction

Size

States

With helperText

With Image

With an error

With custom labels

Legend visibility

Adding a Popover

Writing

Related