Checkbox

We recommending using a Checkbox over a Switch when you have a long list (>3) of toggles.

Props

Component props
Name	Type	Default
`id` Required	`string`	-
`onChange` Required	`({ event: SyntheticInputEvent<>, checked: boolean }) => void`	-
`checked`	`boolean`	`false`
`disabled`	`boolean`	`false`
`errorMessage`	`string`	-
`hasError`	`boolean`	`false`
`image`	`React.Node`	-
	An optional `Image` component can be supplied to add an image to each checkbox. Spacing is already accounted for; simply specify the width and height.
`indeterminate`	`boolean`	`false`
	Indeterminism is purely presentational - the value of a checkbox and its indeterminism are independent.
`label`	`string`	-
`name`	`string`	-
`onClick`	`({ event: SyntheticInputEvent<HTMLInputElement>, checked: boolean }) => void`	-
`ref`	`React.Ref<"input">`	-
	Forward the ref to the underlying input element
`size`	`"sm" \| "md"`	`"md"`
	"sm" is 16px & "md" is 24px
`subtext`	`string`	-
	Optional description for the checkbox, used to provide more detail about an option

Usage guidelines

When to Use

Presenting users with a list of multiple, related options where users can select all, some, or none of the options. With Checkboxes, users can select more than one option.
Presenting users with a single option that can be selected or not.

When Not to Use

Situations where users can only choose one out of multiple, related options. Use RadioButtons instead.
When a selection takes immediate effect, especially on mobile. Use Switch instead.

Example

United States of America

function CheckboxExample() {
  const [checked, setChecked] = React.useState(true);

  return (
      <Checkbox
        checked={checked}
        id="usa"
        label="United States of America"
        name="usa"
        onChange={({ checked }) => {
          setChecked(checked);
        }}
      />
  );
}

function CheckboxExample() {
  const [checked, setChecked] = React.useState(true);
  return (
      <Checkbox
        checked={checked}
        id="usa"
        label="United States of America"
        name="usa"
        onChange={({ checked }) => {
          setChecked(checked);
        }}
      />
  );
}

Example: Group

Here is an example of an accessible group of checkboxes. When creating a group of Checkboxes, be sure to wrap them in a Fieldset.

What languages would you like to learn?

English

Spanish

Chinese

function CheckboxExample() {
    const [checkedEn, setCheckedEn] = React.useState(false);
    const [checkedSp, setCheckedSp] = React.useState(false);
    const [checkedCh, setCheckedCh] = React.useState(false);

  return (
    <Fieldset legend="What languages would you like to learn?">
      <Flex direction="column" gap={2}>
        <Checkbox
          checked={checkedEn}
          id="english"
          label="English"
          name="english"
          onChange={({ checked }) => {
            setCheckedEn(checked);
          }}
        />

        <Checkbox
          checked={checkedSp}
          id="spanish"
          label="Spanish"
          name="spanish"
          onChange={({ checked }) => {
            setCheckedSp(checked);
          }}
        />

        <Checkbox
          checked={checkedCh}
          id="chinese"
          label="Chinese"
          name="chinese"
          onChange={({ checked }) => {
            setCheckedCh(checked);
          }}
        />
      </Flex>
    </Fieldset>
  );
}

function CheckboxExample() {
    const [checkedEn, setCheckedEn] = React.useState(false);
    const [checkedSp, setCheckedSp] = React.useState(false);
    const [checkedCh, setCheckedCh] = React.useState(false);
  return (
    <Fieldset legend="What languages would you like to learn?">
      <Flex direction="column" gap={2}>
        <Checkbox
          checked={checkedEn}
          id="english"
          label="English"
          name="english"
          onChange={({ checked }) => {
            setCheckedEn(checked);
          }}
        />
        <Checkbox
          checked={checkedSp}
          id="spanish"
          label="Spanish"
          name="spanish"
          onChange={({ checked }) => {
            setCheckedSp(checked);
          }}
        />
        <Checkbox
          checked={checkedCh}
          id="chinese"
          label="Chinese"
          name="chinese"
          onChange={({ checked }) => {
            setCheckedCh(checked);
          }}
        />
      </Flex>
    </Fieldset>
  );
}

Example: With Subtext

Here is an example of a group of checkboxes with additional subtext applied.

What languages would you like to learn?

English

USA, India, and Pakistan have the top number of English speakers

Spanish

Mexico, Colombia, and Spain are the top three Spanish-speaking countries

Chinese

Chinese has many varieties, including Cantonese and Mandarin

function CheckboxExample() {
    const [checkedEn, setCheckedEn] = React.useState(false);
    const [checkedSp, setCheckedSp] = React.useState(false);
    const [checkedCh, setCheckedCh] = React.useState(false);

  return (
    <Fieldset legend="What languages would you like to learn?">
      <Flex direction="column" gap={2}>
        <Checkbox
          checked={checkedEn}
          id="english-info"
          label="English"
          subtext="USA, India, and Pakistan have the top number of English speakers "
          name="languages"
          onChange={({ checked }) => {
            setCheckedEn(checked);
          }}
        />
        <Checkbox
          checked={checkedSp}
          id="spanish-info"
          label="Spanish"
          subtext="Mexico, Colombia, and Spain are the top three Spanish-speaking countries"
          name="languages"
          onChange={({ checked }) => {
            setCheckedSp(checked);
          }}
        />
        <Checkbox
          checked={checkedCh}
          id="chinese-info"
          label="Chinese"
          subtext="Chinese has many varieties, including Cantonese and Mandarin"
          name="languages"
          onChange={({ checked }) => {
            setCheckedCh(checked);
          }}
        />
      </Flex>
    </Fieldset>
  );
}

function CheckboxExample() {
    const [checkedEn, setCheckedEn] = React.useState(false);
    const [checkedSp, setCheckedSp] = React.useState(false);
    const [checkedCh, setCheckedCh] = React.useState(false);
  return (
    <Fieldset legend="What languages would you like to learn?">
      <Flex direction="column" gap={2}>
        <Checkbox
          checked={checkedEn}
          id="english-info"
          label="English"
          subtext="USA, India, and Pakistan have the top number of English speakers "
          name="languages"
          onChange={({ checked }) => {
            setCheckedEn(checked);
          }}
        />
        <Checkbox
          checked={checkedSp}
          id="spanish-info"
          label="Spanish"
          subtext="Mexico, Colombia, and Spain are the top three Spanish-speaking countries"
          name="languages"
          onChange={({ checked }) => {
            setCheckedSp(checked);
          }}
        />
        <Checkbox
          checked={checkedCh}
          id="chinese-info"
          label="Chinese"
          subtext="Chinese has many varieties, including Cantonese and Mandarin"
          name="languages"
          onChange={({ checked }) => {
            setCheckedCh(checked);
          }}
        />
      </Flex>
    </Fieldset>
  );
}

Example: With Images

Here is an example of a group of checkboxes with images included. When including images, you can use the subtext property to clearly describe the information being presented by the image, or use the image's alt text to provide more context.

Which backgrounds would you like to use?

Coral

Botanical art in coral and green

Blue

Typography and shoe in blue

function CheckboxExample() {
    const [checkedCoral, setCheckedCoral] = React.useState(false);
    const [checkedBlue, setCheckedBlue] = React.useState(false);

  return (
    <Fieldset legend="Which backgrounds would you like to use?" legendDisplay="hidden">
      <Flex direction="column" gap={4}>
        <Checkbox
          checked={checkedCoral}
          id="coral"
          label="Coral"
          subtext="Botanical art in coral and green"
          image={<Box height={100} width={80}><Image alt="Botanical art in coral and green" src="https://i.ibb.co/7bQQYkX/stock2.jpg" fit="contain" naturalWidth={1} naturalHeight={1}/></Box>}
          name="favorite art"
          onChange={({ checked }) => {
            setCheckedCoral(checked);
          }}
        />
        <Checkbox
          checked={checkedBlue}
          id="blue"
          label="Blue"
          subtext="Typography and shoe in blue"
          image={<Box height={100} width={80}><Image alt="Typography and shoe in blue" src="https://i.ibb.co/jVR29XV/stock5.jpg" fit="contain" naturalWidth={1} naturalHeight={1}/></Box>}
          name="favorite art"
          onChange={({ checked }) => {
            setCheckedBlue(checked);
          }}
        />
      </Flex>
    </Fieldset>
  );
}

function CheckboxExample() {
    const [checkedCoral, setCheckedCoral] = React.useState(false);
    const [checkedBlue, setCheckedBlue] = React.useState(false);
  return (
    <Fieldset legend="Which backgrounds would you like to use?" legendDisplay="hidden">
      <Flex direction="column" gap={4}>
        <Checkbox
          checked={checkedCoral}
          id="coral"
          label="Coral"
          subtext="Botanical art in coral and green"
          image={<Box height={100} width={80}><Image alt="Botanical art in coral and green" src="https://i.ibb.co/7bQQYkX/stock2.jpg" fit="contain" naturalWidth={1} naturalHeight={1}/></Box>}
          name="favorite art"
          onChange={({ checked }) => {
            setCheckedCoral(checked);
          }}
        />
        <Checkbox
          checked={checkedBlue}
          id="blue"
          label="Blue"
          subtext="Typography and shoe in blue"
          image={<Box height={100} width={80}><Image alt="Typography and shoe in blue" src="https://i.ibb.co/jVR29XV/stock5.jpg" fit="contain" naturalWidth={1} naturalHeight={1}/></Box>}
          name="favorite art"
          onChange={({ checked }) => {
            setCheckedBlue(checked);
          }}
        />
      </Flex>
    </Fieldset>
  );
}

Example: Error state

Here is an example of a checkbox showing an error message.

function CheckboxExample() {
  return (
      <Checkbox
        id="error"
        errorMessage="This checkbox has an error"
        label="Email"
        name="error"
        onChange={() => {}}
      />
  );
}

function CheckboxExample() {
  return (
      <Checkbox
        id="error"
        errorMessage="This checkbox has an error"
        label="Email"
        name="error"
        onChange={() => {}}
      />
  );
}

Example: ref

The underlying input element can be accessed via ref.

Toggle Checkbox to small size

24px Checkbox

function CheckboxExample() {
  const ref = React.useRef();
  const [label, setLabel] = React.useState('24');
  const [size, setSize] = React.useState('md');
  const [switched, setSwitched] = React.useState(false);

  React.useEffect(() => {
      setLabel(ref.current && ref.current.offsetHeight)
  }, [size]);

  return (
    <Flex gap={4}>
      <Label htmlFor="emailNotifications">
        <Flex gap={2}>
          <Switch
            onChange={() => {
              setSize(size === "sm" ? "md" : "sm")
              setSwitched(!switched)}
            }
            id="emailNotifications"
            switched={switched}
          />
          <Text>Toggle Checkbox to small size</Text>
        </Flex>

      </Label>
        <Checkbox
          id="sizing"
          checked={true}
          label={`${label}px Checkbox`}
          onChange={() => {} }
          value="value"
          ref={ref}
          size={size}
        />
    </Flex>
  );
}

function CheckboxExample() {
  const ref = React.useRef();
  const [label, setLabel] = React.useState('24');
  const [size, setSize] = React.useState('md');
  const [switched, setSwitched] = React.useState(false);
  React.useEffect(() => {
      setLabel(ref.current && ref.current.offsetHeight)
  }, [size]);
  return (
    <Flex gap={4}>
      <Label htmlFor="emailNotifications">
        <Flex gap={2}>
          <Switch
            onChange={() => {
              setSize(size === "sm" ? "md" : "sm")
              setSwitched(!switched)}
            }
            id="emailNotifications"
            switched={switched}
          />
          <Text>Toggle Checkbox to small size</Text>
        </Flex>
      </Label>
        <Checkbox
          id="sizing"
          checked={true}
          label={`${label}px Checkbox`}
          onChange={() => {} }
          value="value"
          ref={ref}
          size={size}
        />
    </Flex>
  );
}

Edit page on GitHub