import { Checkbox } from "@vitality-ds/components";

Building a form? Checkout out the FormField component

The checkbox is a checkable input for users to communicate if an option is true, false, or indeterminate. A checkbox can appear standalone by itself or in a set of other options. When used in a group of other checkboxes, more than one checkbox can be selected at once.

Checkboxes are used for multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections.

() => {
  const [checked, setChecked] = React.useState(false);
  const [disabled, setDisabled] = React.useState(false);
  const [invalid, setInvalid] = React.useState(false);

  return (
    <DocsBox
      css={{
        backgroundColor: "$neutral1",
        padding: "$xl",
        borderRadius: "$default",
        maxWidth: 380,
        boxShadow: "$sm",
      }}
    >
      <Stack spacing="xl" align="stretch">
        <header>
          <Typography variant="sectionTitle">Checkbox Example</Typography>
          <Typography color="lowContrast">
            The below example provides simple state management to control the
            Checkbox.{" "}
          </Typography>
        </header>
        <Stack direction="horizontal">
          <Checkbox
            label="Do not SMS?"
            value="do_not_sms"
            id="do_not_sms"
            name="contact-options"
            onChange={() => setChecked(!checked)}
            checked={checked}
            disabled={disabled}
          />
        </Stack>
        <Stack direction="horizontal">
          <Button
            type="button"
            size="compact"
            onClick={() =>
              setChecked((prevIsChecked) =>
                prevIsChecked === "indeterminate" ? false : "indeterminate"
              )
            }
          >
            Toggle indeterminate
          </Button>
          <Button
            type="button"
            size="compact"
            onClick={() => setDisabled(!disabled)}
          >
            Toggle disabled
          </Button>
        </Stack>
      </Stack>
    </DocsBox>
  );
};

Often you'll want to display a number of options to choose from. You can choose to either utilise a FormField component which includes labels and error messages, or use a standalone CheckboxList as shown below:

Most cases should be using FormField, as all form elements should also contain a label and any supporting helper/validation messages.

Often a series of checkboxes will refer to the same question, prompt or property that the user is being asked about. As an example, a list of checkboxes may represent a patient's food allergies:

<CheckboxList
  value={[""]}
  name="foodAllergies"
  options={[
    { value: "nuts", label: "Nuts", id: "nuts" },
    { value: "shellfish", label: "Shellfish", id: "shellfish" },
  ]}
/>

In this example each checkbox will be given the same name (foodAllergies). If both checkboxes are checked and then the form is submitted, you'll get a string of name/value pairs submitted like this: `foodAllergies=apples&foodAllergies=bananas``. When this string reaches the server, it can be parsed.

If each Checkbox is completely unrelated, you can just deal with them all separately by passing the name prop for each option (see below). This would result in the following string being submitted to the server:

nuts=nuts&shellfish=shellfish

<CheckboxList
  value={[""]}
  name="allergies"
  options={[
    { value: "mold", label: "Mold", name: "mold", id: "mold" },
    { value: "pollen", label: "Pollen", name: "pollen", id: "pollen" },
  ]}
/>

This component takes all valid <input type="checkbox">attributes. Read more on MDN