Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

Example#

<Checkbox>Unsubscribe</Checkbox>

<Checkbox>Unsubscribe</Checkbox>

<Checkbox>
  Unsubscribe
</Checkbox>

Content#

Checkboxes accept children, which are rendered as the label.

Accessibility#

In certain cases a visible label isn't needed. For example, a checkbox used to select a table row. If a visible label isn't specified, an aria-label must be provided to the Checkbox for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

To internationalize a Checkbox, a localized label should be passed to the children or aria-label prop. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the checkbox is automatically flipped.

Value#

Checkboxes are not selected by default. The defaultSelected prop can be used to set the default state (uncontrolled). Alternatively, the isSelected prop can be used to make the selected state controlled. See React's documentation on uncontrolled components for more info.

function Example() {
  let [selected, setSelected] = React.useState(true);

  return (
    <Flex direction="row">
      <Checkbox defaultSelected>Subscribe (uncontrolled)</Checkbox>
      <Checkbox isSelected={selected} onChange={setSelected}>
        Subscribe (controlled)
      </Checkbox>
    </Flex>
  );
}

function Example() {
  let [selected, setSelected] = React.useState(true);

  return (
    <Flex direction="row">
      <Checkbox defaultSelected>
        Subscribe (uncontrolled)
      </Checkbox>
      <Checkbox
        isSelected={selected}
        onChange={setSelected}
      >
        Subscribe (controlled)
      </Checkbox>
    </Flex>
  );
}

function Example() {
  let [
    selected,
    setSelected
  ] = React.useState(
    true
  );

  return (
    <Flex direction="row">
      <Checkbox
        defaultSelected
      >
        Subscribe
        (uncontrolled)
      </Checkbox>
      <Checkbox
        isSelected={selected}
        onChange={setSelected}
      >
        Subscribe
        (controlled)
      </Checkbox>
    </Flex>
  );
}

Indeterminate#

View guidelines

A Checkbox can be in an indeterminate state, controlled using the isIndeterminate prop. This overrides the appearance of the Checkbox, whether selection is controlled or uncontrolled. The Checkbox will visually remain indeterminate until the isIndeterminate prop is set to false, regardless of user interaction.

<Checkbox isIndeterminate>Subscribe</Checkbox>

<Checkbox isIndeterminate>Subscribe</Checkbox>

<Checkbox
  isIndeterminate
>
  Subscribe
</Checkbox>

Events#

Checkboxes accept a user defined onChange prop, triggered whenever the Checkbox is clicked. The example below uses onChange to alert the user to changes in the checkbox's state.

function Example() {
  let [selected, setSelection] = React.useState(false);

  return (
    <Flex direction="column">
      <Checkbox isSelected={selected} onChange={setSelection}>
        Subscribe
      </Checkbox>
      <View>{`You are ${selected ? 'subscribed' : 'unsubscribed'}`}</View>
    </Flex>
  );
 }

function Example() {
  let [selected, setSelection] = React.useState(false);

  return (
    <Flex direction="column">
      <Checkbox
        isSelected={selected}
        onChange={setSelection}
      >
        Subscribe
      </Checkbox>
      <View>
        {`You are ${
          selected ? 'subscribed' : 'unsubscribed'
        }`}
      </View>
    </Flex>
  );
}

function Example() {
  let [
    selected,
    setSelection
  ] = React.useState(
    false
  );

  return (
    <Flex direction="column">
      <Checkbox
        isSelected={selected}
        onChange={setSelection}
      >
        Subscribe
      </Checkbox>
      <View>
        {`You are ${
          selected
            ? 'subscribed'
            : 'unsubscribed'
        }`}
      </View>
    </Flex>
  );
}

Validation#

Checkboxes can display a validation state to communicate to the user if the current value is invalid. Implement your own validation logic in your app and pass "invalid" to the Checkbox via the validationState prop.

<Checkbox validationState="invalid">
  I accept the terms and conditions
</Checkbox>

<Checkbox validationState="invalid">
  I accept the terms and conditions
</Checkbox>

<Checkbox validationState="invalid">
  I accept the terms
  and conditions
</Checkbox>

Props#

Visual options#

Disabled#

View guidelines

<Checkbox isDisabled>Subscribe</Checkbox>

<Checkbox isDisabled>Subscribe</Checkbox>

<Checkbox isDisabled>
  Subscribe
</Checkbox>

Emphasized#

View guidelines

<Checkbox isEmphasized defaultSelected>Subscribe</Checkbox>

<Checkbox isEmphasized defaultSelected>Subscribe</Checkbox>

<Checkbox
  isEmphasized
  defaultSelected
>
  Subscribe
</Checkbox>