Radio

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

The Radio component works like native radio buttons, allowing you to 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 the checked property, meaning you have to control it with your state. An uncontrolled variant is used when you use the defaultChecked property, allowing you to define the default state and let the browser control the rest afterward.

<View gap={2}>
  <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 the hasError flag. Usually, this is done when displaying a group of radio buttons, and you can likely use the 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 native radio buttons, it will prevent the onChange handler from triggering.

<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={2}>
    <Radio value="dog">Dog</Radio>
    <Radio value="cat">Cat</Radio>
  </View>
</RadioGroup>

As you can see, the 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.

Similarly, while 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={2}>
    <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. This ensures that FormControl resolves the HTML tags correctly for a group of input fields.

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

  <RadioGroup name="animalGroup">
    <View gap={2}>
      <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>