Checkbox

View source on GitHub

Checkbox is used for multiple choice selection. They are independent of each other in a list, and therefore, different from RadioButton, one selection does not affect other checkboxes in the same list.

Props

Component props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the input.
`onChange` Required	`({\| event: SyntheticInputEvent<HTMLInputElement>, checked: boolean \|}) => void`	-
	Callback triggered when the state of the input changes.
`checked`	`boolean`	`false`
	Indicates whether or not Checkbox is checked. See the state variant to learn more.
`disabled`	`boolean`	`false`
	Indicates whether or not Checkbox is disabled. Disabled Checkboxes do not respond to mouse events and cannot be reached by the keyboard. See the state variant to learn more.
`errorMessage`	`string`	-
	Displays an error message and error state. See the accessibility section to learn more.
`hasError`	`boolean`	`false`
	This field is deprecated and will be removed soon. Please do not use.
`image`	`React.Node`	-
	An optional Image can be supplied to add an image to each Checkbox. See the with Image variant to learn more.
`indeterminate`	`boolean`	`false`
	Indicates a state that is neither checked nor unchecked. See the state variant to learn more.
`label`	`string`	-
	The label for the input. Be sure to localize the text. See the accessibility section to learn more.
`labelDisplay`	`"visible" \| "hidden"`	`"visible"`
	Whether the label should be visible or not. If `hidden`, the label is still available for screen reader users, but does not appear visually. See the label visibility variant for more info.
`name`	`string`	-
	A unique name for the input used to reference form data after it’s submitted. If the name attribute is not specified then the data of the checkbox would not be sent in the form submission.
`onClick`	`({\| event: SyntheticInputEvent<HTMLInputElement>, checked: boolean \|}) => void`	-
	Callback triggered when the user clicks on the input.
`ref`	`React.Element<"input">`	-
	Ref that is forwarded to the underlying input element.
`size`	`"sm" \| "md"`	`"md"`
	Determines the Checkbox size: sm = 16px, md = 24px. See the size variant to learn more.
`subtext`	`string`	-
	Optional description for Checkbox, used to provide more detail about an option. See the with subtext variant to learn more.

Usage guidelines

When to use

In a list, form or a Table, to present users with multiple, related options where more than one option can be selected. Users must be able to select all, none or some of the presented options.
In a Form, along with a TextField, or other spaces that are too small for a Switch
When selection doesn’t take immediate effect and requires form submission

When not to use

Situations where users can only choose one out of multiple, related options. Use RadioButton instead.
When a selection takes immediate effect, especially on mobile. Use Switch instead.
When visually, it’s hard to tell that a checkbox turns something on or off. Use Switch instead.

Best practices

Use checkboxes for multi-selection of related list items

Don't

Use checkboxes for one selection. Use RadioButton instead.

Use a single Checkbox in forms where the selection only takes effect after submitting the form

Don't

Use a Checkbox to turn a state on and off with immediate effect. Use Switch instead.

Keep labels and legends clear and brief to avoid too many lines of text that are hard to scan and slow the user down. If clarification is needed, use info Tooltips or subtext.

Don't

Use lengthy text that truncates and doesn’t offer clear instructions for what you are expected to select

Use Checkbox at the start of a table row to make it clear which rows are multi-selectable

Don't

Use numerous checkboxes in table rows that make it hard to tell what items apply to multi-select actions

Accessibility

Labels

Checkboxes should have labels that can be read by screen readers, and that can be clicked or tapped to make it easier for users to select and deselect options. Therefore, make sure to supply the label prop. If that’s not possible, make sure your stand-alone Label has an htmlFor prop that matches the id of the checkbox. Test that a checkbox and label are properly connected by clicking or tapping on the label and confirming that it activates the checkbox next to it.

If Checkbox is labeled by content elsewhere on the page, or a more complex label is needed, the labelDisplay prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen. See the Label visibility example for more detail.

Legends

All groups of related Checkboxes should have a legend, which is provided by wrapping them in Fieldset component.

function Example() {
    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 Example() {
    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>
  );
}

Checkbox has conventional keyboard support.

Users relying on the keyboard expect to move focus to each Checkbox by using the tab key or shift+tab when moving backwards
Setting disabled will prevent Checkbox from receiving keyboard focus or input

In order to ensure proper tab order, wrap a group of related Checkboxes in Fieldset.

Error message

Checkbox’s error state displays an error-themed color border. Checkbox must always show an error message to indicate error status to ensure color is not the only indicator of status or information. Use errorMessage prop to display the appropriate error message that helps the user resolve the problem. Error messages should be clear, direct and conversational. For an example, see Writing.

function CheckboxExample() {
  return (
      <Checkbox
        id="error"
        errorMessage="You must agree to the Terms and Conditions"
        label="I agree to the Terms and Conditions"
        name="error"
        onChange={() => {}}
      />
  );
}

function CheckboxExample() {
  return (
      <Checkbox
        id="error"
        errorMessage="You must agree to the Terms and Conditions"
        label="I agree to the Terms and Conditions"
        name="error"
        onChange={() => {}}
      />
  );
}

Localization

Be sure to localize label and any subtext. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.

Variants

Size

Checkbox has size="sm" (16px) and size='md' (24px).

function Example() {
    const [checked1, setChecked1] = React.useState(false);
    const [checked2, setChecked2] = React.useState(false);

  return (
    <Flex gap={6}>
      <Checkbox
        checked={checked1}
        id="sm"
        label="Small size"
        onChange={({ checked }) => setChecked1(checked)}
        size="sm"
      />
      <Checkbox
        checked={checked2}
        id="md"
        label="Medium size"
        onChange={({ checked }) => setChecked2(checked)}
      />
    </Flex>
  );
}

function Example() {
    const [checked1, setChecked1] = React.useState(false);
    const [checked2, setChecked2] = React.useState(false);

  return (
    <Flex gap={6}>
      <Checkbox
        checked={checked1}
        id="sm"
        label="Small size"
        onChange={({ checked }) => setChecked1(checked)}
        size="sm"
      />
      <Checkbox
        checked={checked2}
        id="md"
        label="Medium size"
        onChange={({ checked }) => setChecked2(checked)}
      />
    </Flex>
  );
}

State

Checkbox has unchecked, checked, error, indeterminate and disabled states.

Indeterminate is a state that is neither checked nor unchecked — e.g. a "Select all" checkbox when not all items are selected or unselected. Indeterminism is purely presentational - the value of a checkbox and its indeterminism are independent.

function Example() {
    const [checked1, setChecked1] = React.useState(false);
    const [checked2, setChecked2] = React.useState(true);
    const [checked3, setChecked3] = React.useState(false);
    const [checked4, setChecked4] = React.useState(false);
    const [checked5, setChecked5] = React.useState(false);

  return (
    <Flex gap={6}>
      <Checkbox
        checked={false}
        id="Unchecked"
        label="Unchecked"
        onChange={() => setChecked1(false)}
      />
      <Checkbox
        checked={checked2}
        id="Checked"
        label="Checked"
        onChange={() => setChecked2(true)}
      />
      <Checkbox
        checked={checked4}
        id="ErrorState"
        label="Error"
        errorMessage="error message"
        onChange={({ checked }) => setChecked4(checked)}
      />
      <Checkbox
        checked={checked3}
        id="Indeterminate"
        label="Indeterminate"
        indeterminate
        onChange={({ checked }) => setChecked3(checked)}
      />
      <Checkbox
        checked={checked4}
        id="Disabled"

        label="Disabled"
        disabled
        onChange={({ checked }) => setChecked4(checked)}
      />

    </Flex>
  );
}

function Example() {
    const [checked1, setChecked1] = React.useState(false);
    const [checked2, setChecked2] = React.useState(true);
    const [checked3, setChecked3] = React.useState(false);
    const [checked4, setChecked4] = React.useState(false);
    const [checked5, setChecked5] = React.useState(false);

  return (
    <Flex gap={6}>
      <Checkbox
        checked={false}
        id="Unchecked"
        label="Unchecked"
        onChange={() => setChecked1(false)}
      />
      <Checkbox
        checked={checked2}
        id="Checked"
        label="Checked"
        onChange={() => setChecked2(true)}
      />
      <Checkbox
        checked={checked4}
        id="ErrorState"
        label="Error"
        errorMessage="error message"
        onChange={({ checked }) => setChecked4(checked)}
      />
      <Checkbox
        checked={checked3}
        id="Indeterminate"
        label="Indeterminate"
        indeterminate
        onChange={({ checked }) => setChecked3(checked)}
      />
      <Checkbox
        checked={checked4}
        id="Disabled"

        label="Disabled"
        disabled
        onChange={({ checked }) => setChecked4(checked)}
      />

    </Flex>
  );
}

With subtext

Checkbox supports subtexts

function Example() {
    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 Example() {
    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>
  );
}

With Image

Checkbox supports images. 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.

Spacing is already accounted for; simply specify the width and height.

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>
  );
}

Label visibility

In some cases, the label for a Checkbox is represented in a different way visually, as demonstrated below. In these instances, you can set labelDisplay="hidden" to ensure Checkbox is properly labeled for screen readers while using a different element to represent the label visually.

function Example() {
  const [checked1, setChecked1] = React.useState(false);
  const [checked2, setChecked2] = React.useState(false);
  const [checked3, setChecked3] = React.useState(false);

  return (
    <Table accessibilityLabel="Campaign selection" maxHeight={200}>
      <Table.Header sticky>
        <Table.Row>
          <Table.HeaderCell/>
          <Table.HeaderCell>
            <Text weight="bold">Name</Text>
          </Table.HeaderCell>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        <Table.Row>
          <Table.Cell>
            <Box width={20}>
              <Checkbox
                checked={checked1}
                id="label-visibility-example-checkbox-1"
                onChange={({ checked }) => setChecked1(checked)}
                label="Select Summertime picnic row"
                labelDisplay="hidden"
                size="sm"
              />
            </Box>
          </Table.Cell>
          <Table.Cell>
            <Text>Summertime picnic</Text>
          </Table.Cell>
        </Table.Row>
        <Table.Row>
          <Table.Cell>
            <Box width={20}>
              <Checkbox
                checked={checked2}
                id="label-visibility-example-checkbox-2"
                onChange={({ checked }) => setChecked2(checked)}
                label="Select Summer 1950 row"
                labelDisplay="hidden"
                size="sm"
              />
            </Box>
          </Table.Cell>
          <Table.Cell>
            <Text>Summer 1950</Text>
          </Table.Cell>
        </Table.Row>
        <Table.Row>
          <Table.Cell>
            <Box width={20}>
              <Checkbox
                checked={checked3}
                id="label-visibility-example-checkbox-3"
                onChange={({ checked }) => setChecked3(checked)}
                label="Select Back to school row"
                labelDisplay="hidden"
                size="sm"
              />
            </Box>
          </Table.Cell>
          <Table.Cell>
            <Text>Back to school</Text>
          </Table.Cell>
        </Table.Row>
      </Table.Body>
    </Table>
  );
}

function Example() {
  const [checked1, setChecked1] = React.useState(false);
  const [checked2, setChecked2] = React.useState(false);
  const [checked3, setChecked3] = React.useState(false);

  return (
    <Table accessibilityLabel="Campaign selection" maxHeight={200}>
      <Table.Header sticky>
        <Table.Row>
          <Table.HeaderCell/>
          <Table.HeaderCell>
            <Text weight="bold">Name</Text>
          </Table.HeaderCell>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        <Table.Row>
          <Table.Cell>
            <Box width={20}>
              <Checkbox
                checked={checked1}
                id="label-visibility-example-checkbox-1"
                onChange={({ checked }) => setChecked1(checked)}
                label="Select Summertime picnic row"
                labelDisplay="hidden"
                size="sm"
              />
            </Box>
          </Table.Cell>
          <Table.Cell>
            <Text>Summertime picnic</Text>
          </Table.Cell>
        </Table.Row>
        <Table.Row>
          <Table.Cell>
            <Box width={20}>
              <Checkbox
                checked={checked2}
                id="label-visibility-example-checkbox-2"
                onChange={({ checked }) => setChecked2(checked)}
                label="Select Summer 1950 row"
                labelDisplay="hidden"
                size="sm"
              />
            </Box>
          </Table.Cell>
          <Table.Cell>
            <Text>Summer 1950</Text>
          </Table.Cell>
        </Table.Row>
        <Table.Row>
          <Table.Cell>
            <Box width={20}>
              <Checkbox
                checked={checked3}
                id="label-visibility-example-checkbox-3"
                onChange={({ checked }) => setChecked3(checked)}
                label="Select Back to school row"
                labelDisplay="hidden"
                size="sm"
              />
            </Box>
          </Table.Cell>
          <Table.Cell>
            <Text>Back to school</Text>
          </Table.Cell>
        </Table.Row>
      </Table.Body>
    </Table>
  );
}

Writing

Be clear and brief with checkbox labels so they are easily scanned

Don't

Include lengthy text labels that make it hard for a user to scan a list of choices

RadioButton
Use when presenting a user with a list of choices for which there can only be one selection.

Switch
Use for single-cell options that can be turned on or off. Examples include a list of settings that take effect immediately without having to confirm Form submission.

Fieldset
Use to group a list of related Checkboxes with a legend that describes the list.

Edit page on GitHub

Checkbox

Props

Usage guidelines

Best practices

Accessibility

Labels

Legends

Keyboard navigation

Error message

Localization

Variants

Size

State

With subtext

With Image

Label visibility

Writing

Related