Radio

<Radio value="ice-cream">Ice cream</Radio>

Radio component works like native radio buttons, which means you can either use its value property to define what will be passed to the form when it's submitted.

<Radio name="animal" value="dog" onChange={({ value, name, event }) => {}}>
  Dog
</Radio>

Like all native inputs in React, Radio supports controlled and uncontrolled options. It becomes controlled when you use checked property, which means you have to control it with your state. An uncontrolled variant is used when you use the defaultChecked property, which lets you define the default state and allow the browser to control the rest afterward.

Note: You shouldn't be using both properties simultaneously, and React will throw a warning if that happens.

<View gap={3}>
  <Radio name="animalControlled" value="dog" checked={true}>
    Controlled
  </Radio>
  <Radio name="animalUncontrolled" value="cat" defaultChecked={true}>
    Uncontrolled
  </Radio>
</View>

Since Radio is an exclusive selection - you can't deselect a checked item unless you select another one with the same name.

If there is an error related to the radio field, you can use a hasError flag. Usually, you would do this only when displaying a group of radio buttons, and you can likely use RadioGroup component for that instead.

<Radio hasError name="animalError" value="dog">
  Dog
</Radio>

To make Radio non-interactive, you can use the disabled flag. Like in native radio buttons, it will prevent the onChange handler from triggering.

Note: Disabled state fades the component content. Even though it's not required to have a regular contrast ratio for disabled elements, make not to use it over a gray background.

<Radio disabled name="animalDisabled" value="dog">
  Dog
</Radio>

Most of the time, you will be rendering groups of radio buttons, which you can do with the RadioGroup component. It handles the selection of radio buttons and lets you receive the current value of the group. At the same time, it doesn't enforce any specific layout, so you're free to use any layout components.

<RadioGroup
  name="animalComposition"
  onChange={({ value }) => console.log(value)}
>
  <View gap={3}>
    <Radio value="dog">Dog</Radio>
    <Radio value="cat">Cat</Radio>
  </View>
</RadioGroup>

As you can see, name and onChange properties apply to all Radio components within its scope. You will get the currently selected value logged into the console by choosing a specific Radio.

In the same way, Radio can define its checked value, RadioGroup supports value and defaultValue to control the selection in the options list.

<RadioGroup name="animalValue" defaultValue="cat">
  <View gap={3}>
    <Radio value="dog">Dog</Radio>
    <Radio value="cat">Cat</Radio>
  </View>
</RadioGroup>

If you need to provide a label for a group of radio buttons, you can use the FormControl utility with the group flag turned on. That will resolve FormControl HTML tags correctly for a group of input fields.

<FormControl group>
  <FormControl.Label>Favorite animals:</FormControl.Label>

  <RadioGroup name="animalGroup">
    <View gap={3}>
      <Radio value="dog">Dog</Radio>
      <Radio value="cat">Cat</Radio>
    </View>
  </RadioGroup>
</FormControl>

Both Radio and RadioGroup support content composition. Since RadioGroup doesn't provide any markup, you can use it with any layout components. For the Radio component, you can render multiple elements as its children.

<RadioGroup name="animalCustom" defaultValue="cat">
  <View gap={3}>
    <Card as="label">
      <View gap={3} direction="row" align="center">
        <Radio value="dog" />
        <View.Item grow>
          <Text variant="body-strong-1">Dog</Text>
          <Text variant="body-2">
            The dog is a domesticated animal of the family Canidae.
          </Text>
        </View.Item>
      </View>
    </Card>

    <Card as="label">
      <View gap={3} direction="row" align="center">
        <Radio value="cat" />
        <View.Item grow>
          <Text variant="body-strong-1">Cat</Text>
          <Text variant="body-2">
            The cat is a domesticated animal of the family Felidae.
          </Text>
        </View.Item>
      </View>
    </Card>
  </View>
</RadioGroup>