Checkbox

View Source

Checkboxes are most commonly used to give users a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have a user indicate that they agree to specific terms and conditions.

Peach

Watermelon

Orange

render(
  <StackView axis="horizontal" spacing={2} paddingVertical={2}>
    <Checkbox name="checkbox" size="md" value="peach" label="Peach" />
    <Checkbox name="checkbox" size="md" value="watermelon" label="Watermelon" />
    <Checkbox name="checkbox" size="md" value="orange" label="Orange" />
  </StackView>
)

render(
  <StackView axis="horizontal" spacing={2} paddingVertical={2}>
    <Checkbox name="checkbox" size="md" value="peach" label="Peach" />
    <Checkbox name="checkbox" size="md" value="watermelon" label="Watermelon" />
    <Checkbox name="checkbox" size="md" value="orange" label="Orange" />
  </StackView>
)

Checkbox states

render(() => {
  const options = [
    { value: 'option-1', label: 'Option 1' },
    { value: 'option-2', label: 'Option 2' },
    { value: 'option-3', label: 'Option 3' },
  ]

  const [childOptionChecked, setchildOptionChecked] = React.useState(
    options.map(() => false)
  )

  const toggleChildChecked = (index) =>
    setchildOptionChecked((prev) =>
      prev.map((isChecked, i) => (i === index ? !isChecked : isChecked))
    )

  const allChildrenChecked = childOptionChecked.every(Boolean)
  const someChildrenChecked = childOptionChecked.some(Boolean)
  const indeterminate = !allChildrenChecked && someChildrenChecked

  const toggleAll = () =>
    setchildOptionChecked(childOptionChecked.map(() => !allChildrenChecked))

  return (
    <StackView
      axis="vertical"
      spacing={4}
      paddingVertical={2}
      alignment="center"
    >
      <StackView axis="horizontal" spacing={2} paddingVertical={2}>
        <Checkbox size="md" value="default" label="default" checked={false} />
        <Checkbox size="md" value="checked" label="checked" checked={true} />
        <Checkbox
          size="md"
          value="disabled"
          label="disabled"
          checked={false}
          disabled={true}
        />
        <Checkbox
          size="md"
          value="disabled-checked"
          label="disabled/checked"
          checked={true}
          disabled={true}
        />
      </StackView>
      <StackView
        axis="vertical"
        distribution="start"
        alignment="start"
        width="100%"
      >
        <Checkbox
          size="md"
          value="options"
          label="Options"
          checked={allChildrenChecked}
          indeterminate={indeterminate}
          onChange={toggleAll}
        />
        <Text fontSize={4} color="grey-7" paddingLeft={2.5}>
          state:{' '}
          {indeterminate
            ? 'indeterminate'
            : allChildrenChecked
            ? 'checked'
            : 'unchecked'}
        </Text>
        <StackView axis="vertical" spacing={1} paddingLeft={3} marginTop={1}>
          {options.map((option, index) => (
            <Checkbox
              key={option.value}
              size="md"
              value={option.value}
              label={option.label}
              checked={childOptionChecked[index]}
              onChange={() => toggleChildChecked(index)}
            />
          ))}
        </StackView>
      </StackView>
    </StackView>
  )
})

render(() => {
  const options = [
    { value: 'option-1', label: 'Option 1' },
    { value: 'option-2', label: 'Option 2' },
    { value: 'option-3', label: 'Option 3' },
  ]
  const [childOptionChecked, setchildOptionChecked] = React.useState(
    options.map(() => false)
  )
  const toggleChildChecked = (index) =>
    setchildOptionChecked((prev) =>
      prev.map((isChecked, i) => (i === index ? !isChecked : isChecked))
    )
  const allChildrenChecked = childOptionChecked.every(Boolean)
  const someChildrenChecked = childOptionChecked.some(Boolean)
  const indeterminate = !allChildrenChecked && someChildrenChecked
  const toggleAll = () =>
    setchildOptionChecked(childOptionChecked.map(() => !allChildrenChecked))
  return (
    <StackView
      axis="vertical"
      spacing={4}
      paddingVertical={2}
      alignment="center"
    >
      <StackView axis="horizontal" spacing={2} paddingVertical={2}>
        <Checkbox size="md" value="default" label="default" checked={false} />
        <Checkbox size="md" value="checked" label="checked" checked={true} />
        <Checkbox
          size="md"
          value="disabled"
          label="disabled"
          checked={false}
          disabled={true}
        />
        <Checkbox
          size="md"
          value="disabled-checked"
          label="disabled/checked"
          checked={true}
          disabled={true}
        />
      </StackView>
      <StackView
        axis="vertical"
        distribution="start"
        alignment="start"
        width="100%"
      >
        <Checkbox
          size="md"
          value="options"
          label="Options"
          checked={allChildrenChecked}
          indeterminate={indeterminate}
          onChange={toggleAll}
        />
        <Text fontSize={4} color="grey-7" paddingLeft={2.5}>
          state:{' '}
          {indeterminate
            ? 'indeterminate'
            : allChildrenChecked
            ? 'checked'
            : 'unchecked'}
        </Text>
        <StackView axis="vertical" spacing={1} paddingLeft={3} marginTop={1}>
          {options.map((option, index) => (
            <Checkbox
              key={option.value}
              size="md"
              value={option.value}
              label={option.label}
              checked={childOptionChecked[index]}
              onChange={() => toggleChildChecked(index)}
            />
          ))}
        </StackView>
      </StackView>
    </StackView>
  )
})

Checkbox sizes

Small

Medium

Large

render(
  <StackView axis="horizontal" spacing={2} paddingVertical={2}>
    <Checkbox size="sm" value="small" label="Small" />
    <Checkbox size="md" value="medium" label="Medium" />
    <Checkbox size="lg" value="large" label="Large" />
  </StackView>
)

render(
  <StackView axis="horizontal" spacing={2} paddingVertical={2}>
    <Checkbox size="sm" value="small" label="Small" />
    <Checkbox size="md" value="medium" label="Medium" />
    <Checkbox size="lg" value="large" label="Large" />
  </StackView>
)

Custom theme

checkbox: {
    fill: 'surface',
    stroke: 'grey-6',
    focusStroke: 'interaction-dark',
    checkedFill: 'interaction',
    checkedStroke: 'interaction',
    disabled: {
      fill: 'grey-2',
      stroke: 'grey-4',
      checkedFill: 'grey-6',
      checkedStroke: 'grey-6',
      opacity: 1,
    },
  }

render(
  <ThemeProvider
    theme={{
      checkbox: {
        fill: 'surface',
        stroke: 'grey-6',
        focusStroke: 'interaction-dark',
        checkedFill: 'interaction',
        checkedStroke: 'interaction',
        disabled: {
          fill: 'grey-2',
          stroke: 'grey-4',
          checkedFill: 'grey-6',
          checkedStroke: 'grey-6',
          opacity: 1,
        },
      },
    }}
  >
    <StackView
      axis="vertical"
      spacing={4}
      paddingVertical={2}
      alignment="center"
    >
      <StackView axis="horizontal" spacing={3} width="100%" alignment="start">
        <Checkbox name="checkbox" size="md" value="option-1" label="Option 1" />
        <Checkbox name="checkbox" size="md" value="option-2" label="Option 2" />
        <Checkbox name="checkbox" size="md" value="option-3" label="Option 3" />
      </StackView>
      <Divider />
      <StackView axis="horizontal" spacing={3} width="100%" alignment="start">
        <Checkbox size="md" value="default" label="default" checked={false} />
        <Checkbox size="md" value="checked" label="checked" checked={true} />
        <Checkbox
          size="md"
          value="indeterminate"
          label="indeterminate"
          indeterminate={true}
          checked={false}
        />
      </StackView>
      <StackView axis="horizontal" spacing={3} width="100%" alignment="start">
        <Checkbox
          size="md"
          value="disabled"
          label="disabled"
          checked={false}
          disabled={true}
        />
        <Checkbox
          size="md"
          value="disabled-checked"
          label="disabled/checked"
          checked={true}
          disabled={true}
        />
      </StackView>
    </StackView>
  </ThemeProvider>
)

render(
  <ThemeProvider
    theme={{
      checkbox: {
        fill: 'surface',
        stroke: 'grey-6',
        focusStroke: 'interaction-dark',
        checkedFill: 'interaction',
        checkedStroke: 'interaction',
        disabled: {
          fill: 'grey-2',
          stroke: 'grey-4',
          checkedFill: 'grey-6',
          checkedStroke: 'grey-6',
          opacity: 1,
        },
      },
    }}
  >
    <StackView
      axis="vertical"
      spacing={4}
      paddingVertical={2}
      alignment="center"
    >
      <StackView axis="horizontal" spacing={3} width="100%" alignment="start">
        <Checkbox name="checkbox" size="md" value="option-1" label="Option 1" />
        <Checkbox name="checkbox" size="md" value="option-2" label="Option 2" />
        <Checkbox name="checkbox" size="md" value="option-3" label="Option 3" />
      </StackView>
      <Divider />
      <StackView axis="horizontal" spacing={3} width="100%" alignment="start">
        <Checkbox size="md" value="default" label="default" checked={false} />
        <Checkbox size="md" value="checked" label="checked" checked={true} />
        <Checkbox
          size="md"
          value="indeterminate"
          label="indeterminate"
          indeterminate={true}
          checked={false}
        />
      </StackView>
      <StackView axis="horizontal" spacing={3} width="100%" alignment="start">
        <Checkbox
          size="md"
          value="disabled"
          label="disabled"
          checked={false}
          disabled={true}
        />
        <Checkbox
          size="md"
          value="disabled-checked"
          label="disabled/checked"
          checked={true}
          disabled={true}
        />
      </StackView>
    </StackView>
  </ThemeProvider>
)

Props

Accepts StackView props.

checkedboolean

Checks the checkbox, will be overriden if indeterminate is true.

disabledboolean

Disables the checkbox component.

idstring | number

Connects input to its corresponding label’s htmlFor.

indeterminateboolean

If true, puts the checkbox in an indeterminate state.

labelstring | null

Used to label the checkbox. Checkbox must have parent label if left undefined. Pass null to use as a graphical element only, please note you need to provide additional aria attributes when doing so.

namestring

Maps to the internal input’s name prop.

onBlur(event: React.ChangeEvent<HTMLInputElement>) => void

Maps to the internal input’s onBlur prop.

onChange(event: React.ChangeEvent<HTMLInputElement>) => void

Maps to the internal input’s onChange prop.

onFocus(event: React.ChangeEvent<HTMLInputElement>) => void

Maps to the internal input’s onFocus prop.

size'xs' | 'sm' | 'md' | 'lg' | 'xl'

Determines the size of the checkbox.

valueany

Maps to the internal input’s value prop.

Checkbox states
Checkbox sizes
Custom theme
Props

PreviousTooltip NextCheckboxCard