Radio

Radio buttons are a common way to allow users to make a single selection from a list of options. Only one radio button within a group can be selected at a time, so each available choice is its own item / label.

Radio button label

Design guidance

When and how to use this

Use grouped radio buttons if the user is required to choose one and only one item from a list of 2 or more options.

When to consider something else

For cases where the user should be able to return to a “nothing is selected” state, or if the user can skip choosing an option altogether, consider using a Select instead.

Figma

Drag in a Radio Field Group from the Compositions section in the Form Controls v2 library in your Assets pane. We provide default and error states as well as a required attribute for the field. A Radio Field component is nested within, which then nests an atomic Radio Button component inside. To set the checked attribute and state on a button within the Radio Field Group, select the nested Radio Button and use Figma's component property pane to make changes.

React

Radio composes Chakra’s Radio. We offer size variants that align with those in TextInput. We also offer a RadioGroup that wraps a set of Radio components, controls their values, and distributes some common props such as size and isDisabled, and a TileRadio that offers a radio button wrapped in a tile-like element and offers more text styling options.

live

<Stack direction="column" spacing="400">
  <Radio>I'm idle</Radio>
  <Radio isChecked>I'm checked</Radio>
  <Radio isInvalid>I'm invalid</Radio>
  <Radio isDisabled>I'm disabled</Radio>
</Stack>

Prop	Description
`size`	Sets the size of the Radio and its associated label.
`isChecked`	if `true`, the Radio will be checked. You'll need to pass `onChange` to update its value (since it is now controlled).
`isDisabled`	if `true`, the Radio will be disabled.
`isInvalid`	if `true`, the Radio will be invalid and its `aria-invalid` will be set to `true`.

Radio Group

Use a RadioGroup for most common radio button set use cases. It uses the same props as the basic Radio and applies these across each radio button in the group. In addition you can use the defaultValue prop on this component to set one of the radio buttons as checked by default.

live

<RadioGroup defaultValue="1">
  <Stack direction="column" spacing="400">
    <Radio value="1">Radio 1</Radio>
    <Radio value="2">Radio 2</Radio>
    <Radio value="3">Radio 3</Radio>
  </Stack>
</RadioGroup>

Size

Radio is available in three sizes and defaults to medium. The size set on RadioGroup will be distributed to child Radio components.

live

<Stack spacing="400">
  <RadioGroup size="small" defaultValue="1">
    <HStack justifyContent="space-around">
      <Radio value="1">Small 1</Radio>
      <Radio value="2">Small 2</Radio>
      <Radio value="3">Small 3</Radio>
    </HStack>
  </RadioGroup>
  <Divider />
  <RadioGroup size="medium" defaultValue="1">
    <HStack justifyContent="space-around">
      <Radio value="1">Medium 1</Radio>
      <Radio value="2">Medium 2</Radio>
      <Radio value="3">Medium 3</Radio>
    </HStack>
  </RadioGroup>
  <Divider />
  <RadioGroup size="large" defaultValue="1">
    <HStack justifyContent="space-around">
      <Radio value="1">Large 1</Radio>
      <Radio value="2">Large 2</Radio>
      <Radio value="3">Large 3</Radio>
    </HStack>
  </RadioGroup>
</Stack>

Filled Variant

Radio is available in an alternative style as the filled variant. However, the default variant should usually be used in forms, especially alongside checkboxes.

live

<NextProvider attach fontsHost="/typography/">
  <Stack spacing="400">
    <RadioGroup size="small" defaultValue="1">
      <HStack justifyContent="space-around">
        <Radio variant="filled" value="1">
          Small 1
        </Radio>
        <Radio variant="filled" value="2">
          Small 2
        </Radio>
        <Radio variant="filled" value="3">
          Small 3
        </Radio>
      </HStack>
    </RadioGroup>
    <Divider />
    <RadioGroup size="medium" defaultValue="1">
      <HStack justifyContent="space-around">
        <Radio variant="filled" value="1">
          Medium 1
        </Radio>
        <Radio variant="filled" value="2">
          Medium 2
        </Radio>
        <Radio variant="filled" value="3">
          Medium 3
        </Radio>
      </HStack>
    </RadioGroup>
    <Divider />
    <RadioGroup size="large" defaultValue="1">
      <HStack justifyContent="space-around">
        <Radio variant="filled" value="1">
          Large 1
        </Radio>
        <Radio variant="filled" value="2">
          Large 2
        </Radio>
        <Radio variant="filled" value="3">
          Large 3
        </Radio>
      </HStack>
    </RadioGroup>
  </Stack>
</NextProvider>

Color mode

By default, Radio uses the color mode context to determine whether to display a control for dark or light backgrounds. Pass colorMode to manually force a color mode.

live

<RadioGroup
  display="flex"
  defaultValue="light"
  flexDirection="column"
  gap="300"
  alignItems="start"
>
  <HStack background="neutral.0" borderRadius="300" spacing="500" padding="500">
    <Radio colorMode="light" value="light">
      Light
    </Radio>
    <Radio colorMode="light" variant="filled" value="light-filled">
      Light
    </Radio>
  </HStack>
  <HStack background="neutral.875" borderRadius="300" spacing="500" padding="500">
    <Radio colorMode="dark" value="dark">
      Dark
    </Radio>
    <Radio colorMode="dark" variant="filled" value="dark-filled">
      Dark
    </Radio>
  </SimpleGrid>
</RadioGroup>

Radio control

The animated check control that's used in Radio is available as an independent component, for use in custom radios.

Indicator only

Note

Make sure to implement accessibility correctly when using only the indicator from RadioControl. If the custom component rendering RadioControl is a checkbox, use useRadio.

live

() => {
  const [isChecked, setIsChecked] = useState(true);
  return (
    <HStack>
      <RadioControl size="large" variant="filled" isChecked={isChecked} />
      <Toggle isChecked={isChecked} onChange={() => setIsChecked(!isChecked)}>
        <Code>isChecked</Code>
      </Toggle>
    </HStack>
  );
};

With input and `useRadio`

When using RadioControl directly in a custom radio component that uses useRadio for its state, pass inputProps and radioProps and RadioControl will automatically render the hidden <input type="radio"> in the correct state.

Warning

When using radioProps and inputProps, don't pass isChecked, isInvalid, or isDisabled as that will interfere with the state provided by useRadio.

live

() => {
  const { getInputProps, getRadioProps, getLabelProps, getRootProps, state } =
    useRadio({ value: 'custom-radio' });
  return (
    <HStack as="label" {...getRootProps()}>
      {/* if your radio has a separate label, you'll want to pass it `getLabelProps` */}
      <RadioControl
        inputProps={getInputProps()}
        radioProps={getRadioProps()}
        size="large"
        variant="filled"
      />
      <Code>{JSON.stringify(state)}</Code>
    </HStack>
  );
};

Tile Radio

TileRadio allows for both a label as in the standard Radio component, but also offers a description prop to set secondary text in the tile. It also offers an isSubtle prop to remove the border of the element in its default state. You can wrap a set of TileRadio components in a RadioGroup just like the standard Radio.

live

<Stack direction="column" spacing="400">
  <TileRadio description="Description goes here">I'm idle</TileRadio>
  <TileRadio description="Description goes here" isChecked>
    I'm checked
  </TileRadio>
  <TileRadio description="Description goes here" isInvalid>
    I'm invalid
  </TileRadio>
  <TileRadio description="Description goes here" isDisabled>
    I'm disabled
  </TileRadio>
</Stack>

Bootstrap

Bootstrap provides styles for input type=”radio” and accompanying label elements, using the .form-check-input and .form-check-label classes wrapped in a div with the class .form-check. Wrap groups of these in a fieldset and use the .form-label class on its legend to achieve the same effect as the React RadioGroup.

live

<fieldset>
  <legend class="form-label mb-6">Radio field</legend>
  <div class="form-check">
    <input
      class="form-check-input"
      type="radio"
      name="exampleRadios"
      id="exampleRadios1"
      value="option1"
      checked
    />
    <label class="form-check-label" for="exampleRadios1"> First radio </label>
  </div>
  <div class="form-check">
    <input
      class="form-check-input"
      type="radio"
      name="exampleRadios"
      id="exampleRadios2"
      value="option2"
    />
    <label class="form-check-label" for="exampleRadios2"> Second radio </label>
  </div>
  <div class="form-check">
    <input
      class="form-check-input"
      type="radio"
      name="exampleRadios"
      id="exampleRadios3"
      value="option3"
    />
    <label class="form-check-label" for="exampleRadios3">
      Third radio is third
    </label>
  </div>
</fieldset>

Class	Description
`.form-check-input` and `.form-check-label`	Invokes Bootstrap theme styles for checkboxes and accompanying labels.
`.form-check`	Required class on a wrapper `div` around the checkbox and label elements.
`.form-label`	Invokes Bootstrap theme styles for the `legend` on a `fieldset` that wraps a `.form-check` div and its children, as shown above.

Progress

RadioButton

Design System

Settings

Radio

Design guidance

When and how to use this

When to consider something else

Figma

React

Radio Group

Size

Filled Variant

Color mode

Radio control

Indicator only

Note

With input and `useRadio`

Warning

Tile Radio

Bootstrap

Radio

Design guidance

When and how to use this

When to consider something else

Figma

React

Radio Group

Size

Filled Variant

Color mode

Radio control

Indicator only

Note

With input and useRadio

Warning

Tile Radio

Bootstrap

With input and `useRadio`