Checkbox

Checkbox component works like native checkboxes, meaning you can use its value property to define what will be passed to the form upon submission. Note that it is required to pass a name to the Checkbox.

<Checkbox
  name="animal"
  value="dog"
  onChange={({ value, name, event }) => console.log({ value, name, event })}
>
  Dog
</Checkbox>

If there is an error related to the checkbox field, you can use the hasError flag.

<Checkbox hasError={true} name="animal" value="dog">
  Dog
</Checkbox>

To make the Checkbox non-interactive, use the disabled flag. Like in a native checkbox, this will prevent the onChange handler from triggering.

<Checkbox disabled name="animal" value="dog">
  Dog
</Checkbox>

When Checkbox is used as a parent field for another checkbox group, you can use the indeterminate flag to indicate that some items in the group are selected. The JS API of the inputs controls the indeterminate state, so by default, it will check the Checkbox when you click it. If you want to avoid that, use a controlled component variant.

<Checkbox indeterminate name="animal" value="dog">
  Dog
</Checkbox>

Same as when using native inputs in React, Checkbox can be used as a controlled or uncontrolled component. By default, Checkbox is uncontrolled and lets you define its default value using the defaultChecked property. In this case, all change events are handled automatically. This approach is helpful when you're pre-filling a form from a data source, but you don't need to control the further behavior of the input.

<Checkbox name="animal" value="dog" defaultChecked>
  Dog
</Checkbox>

If you need to control the state of the field manually, use the checked property. This gives you complete control of the component value and stops automatic value handling. You will need to update the state using the onChange handler, allowing you to add custom logic before that happens.

<Checkbox name="animal" value="dog" checked>
  Dog
</Checkbox>

In products, we sometimes work with checkbox groups to select multiple values from a list of options. CheckboxGroup handles this interaction, allowing you to work with multiple checkboxes represented by an array of values. It does not enforce any specific layout, so you are free to use it with any layout components.

<CheckboxGroup
  name="animalComposition"
  onChange={({ value }) => console.log(value)}
>
  <View gap={2}>
    <Checkbox value="dog">Dog</Checkbox>
    <Checkbox value="cat">Cat</Checkbox>
  </View>
</CheckboxGroup>

As you can see, the name and onChange properties apply to all Checkbox components within its scope. By choosing a specific Checkbox, you will get an array with the selected value logged into the console.

Just as Checkbox can define its checked property, CheckboxGroup supports value and defaultValue to control the selection in the options list.

<CheckboxGroup name="animalValue" defaultValue={["cat"]}>
  <View gap={2}>
    <Checkbox value="dog">Dog</Checkbox>
    <Checkbox value="cat">Cat</Checkbox>
  </View>
</CheckboxGroup>

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

<CheckboxGroup name="animalCustom" defaultValue={["cat"]}>
  <View gap={3}>
    <Card as="label">
      <View gap={3} direction="row" align="center">
        <Checkbox value="dog" />
        <View.Item grow>
          <Text variant="body-2" weight="bold">
            Dog
          </Text>
          <Text variant="body-3">
            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">
        <Checkbox value="cat" />
        <View.Item grow>
          <Text variant="body-2" weight="bold">
            Cat
          </Text>
          <Text variant="body-3">
            The cat is a domesticated animal of the family Felidae.
          </Text>
        </View.Item>
      </View>
    </Card>
  </View>
</CheckboxGroup>

If you need to provide a label for a group of checkboxes, use the FormControl utility with the group flag turned on. This will correctly set the FormControl HTML tags for a group of input fields.

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

  <CheckboxGroup name="animalGroup">
    <View gap={2}>
      <Checkbox value="dog">Dog</Checkbox>
      <Checkbox value="cat">Cat</Checkbox>
    </View>
  </CheckboxGroup>
</FormControl>

• When using Checkbox without children, wrap it with a label element.