Checkbox

The Checkbox component is used in forms when a user needs to select multiple values from several options.

Native HTML checkboxes are 100% accessible by default, so we used a very common CSS technique to style the checkboxes.

Import#

import { Checkbox, CheckboxGroup } from "@chakra-ui/core"

import { Checkbox, CheckboxGroup } from "@chakra-ui/core"

Usage#

Basic usage of checkbox.

Checkbox

<Checkbox defaultIsChecked>Checkbox</Checkbox>

<Checkbox defaultIsChecked>Checkbox</Checkbox>

Editable Example

Disabled Checkbox#

Checkbox

<Stack spacing={10} direction="row">
  <Checkbox isDisabled>Checkbox</Checkbox>
  <Checkbox isDisabled defaultIsChecked>
    Checkbox
  </Checkbox>
</Stack>

<Stack spacing={10} direction="row">
  <Checkbox isDisabled>Checkbox</Checkbox>
  <Checkbox isDisabled defaultIsChecked>
    Checkbox
  </Checkbox>
</Stack>

Editable Example

Checkbox with custom color#

You can override the color scheme of the checkbox to any color key specified in theme.colors.

Checkbox

<Stack spacing={10} direction="row">
  <Checkbox colorScheme="red" defaultIsChecked>
    Checkbox
  </Checkbox>
  <Checkbox colorScheme="green" defaultIsChecked>
    Checkbox
  </Checkbox>
</Stack>

<Stack spacing={10} direction="row">
  <Checkbox colorScheme="red" defaultIsChecked>
    Checkbox
  </Checkbox>
  <Checkbox colorScheme="green" defaultIsChecked>
    Checkbox
  </Checkbox>
</Stack>

Editable Example

Checkbox sizes#

Pass the size prop to change the size of the Checkbox. Values can be either sm, md or lg.

Checkbox

<HStack spacing={10} direction="row">
  <Checkbox size="sm" colorScheme="red">
    Checkbox
  </Checkbox>
  <Checkbox size="md" colorScheme="green" defaultIsChecked>
    Checkbox
  </Checkbox>
  <Checkbox size="lg" colorScheme="orange" defaultIsChecked>
    Checkbox
  </Checkbox>
</HStack>

<HStack spacing={10} direction="row">
  <Checkbox size="sm" colorScheme="red">
    Checkbox
  </Checkbox>
  <Checkbox size="md" colorScheme="green" defaultIsChecked>
    Checkbox
  </Checkbox>
  <Checkbox size="lg" colorScheme="orange" defaultIsChecked>
    Checkbox
  </Checkbox>
</HStack>

Editable Example

Invalid Checkbox#

Checkbox

<Checkbox isInvalid>Checkbox</Checkbox>

<Checkbox isInvalid>Checkbox</Checkbox>

Editable Example

Changing the spacing#

We added the spacing prop to customize the spacing between the checkbox and label text

<Checkbox spacing="1rem">Option</Checkbox>

<Checkbox spacing="1rem">Option</Checkbox>

Changing the icon color and size#

You can customize the color and size of the check icon by passing the iconColor and iconSize prop.

<Checkbox iconColor="blue.400" iconSize="1rem">
  Option
</Checkbox>

<Checkbox iconColor="blue.400" iconSize="1rem">
  Option
</Checkbox>

Indeterminate#

Parent Checkbox

Child Checkbox 1

Child Checkbox 2

function IndeterminateExample() {
  const [checkedItems, setCheckedItems] = React.useState([false, false])

  const allChecked = checkedItems.every(Boolean)
  const isIndeterminate = checkedItems.some(Boolean) && !allChecked

  return (
    <>
      <Checkbox
        isChecked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
      >
        Parent Checkbox
      </Checkbox>
      <Stack pl={6} mt={1} spacing={1}>
        <Checkbox
          isChecked={checkedItems[0]}
          onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
        >
          Child Checkbox 1
        </Checkbox>
        <Checkbox
          isChecked={checkedItems[1]}
          onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
        >
          Child Checkbox 2
        </Checkbox>
      </Stack>
    </>
  )
}

function IndeterminateExample() {
  const [checkedItems, setCheckedItems] = React.useState([false, false])
  const allChecked = checkedItems.every(Boolean)
  const isIndeterminate = checkedItems.some(Boolean) && !allChecked
  return (
    <>
      <Checkbox
        isChecked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
      >
        Parent Checkbox
      </Checkbox>
      <Stack pl={6} mt={1} spacing={1}>
        <Checkbox
          isChecked={checkedItems[0]}
          onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
        >
          Child Checkbox 1
        </Checkbox>
        <Checkbox
          isChecked={checkedItems[1]}
          onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
        >
          Child Checkbox 2
        </Checkbox>
      </Stack>
    </>
  )
}

Editable Example

Icon#

Default

Hello world

Indeterminate

Parent Checkbox

Child Checkbox 1

Child Checkbox 2

function WithCustomIconExample() {
  const [checkedItems, setCheckedItems] = React.useState([false, false])

  const allChecked = checkedItems.every(Boolean)
  const isIndeterminate = checkedItems.some(Boolean) && !allChecked

  function CustomIcon(props) {
    const { isIndeterminate, ...rest } = props

    const d = isIndeterminate
      ? "M12,0A12,12,0,1,0,24,12,12.013,12.013,0,0,0,12,0Zm0,19a1.5,1.5,0,1,1,1.5-1.5A1.5,1.5,0,0,1,12,19Zm1.6-6.08a1,1,0,0,0-.6.917,1,1,0,1,1-2,0,3,3,0,0,1,1.8-2.75A2,2,0,1,0,10,9.255a1,1,0,1,1-2,0,4,4,0,1,1,5.6,3.666Z"
      : "M0,12a1.5,1.5,0,0,0,1.5,1.5h8.75a.25.25,0,0,1,.25.25V22.5a1.5,1.5,0,0,0,3,0V13.75a.25.25,0,0,1,.25-.25H22.5a1.5,1.5,0,0,0,0-3H13.75a.25.25,0,0,1-.25-.25V1.5a1.5,1.5,0,0,0-3,0v8.75a.25.25,0,0,1-.25.25H1.5A1.5,1.5,0,0,0,0,12Z"

    return (
      <Icon viewBox="0 0 24 24" {...rest}>
        <path fill="currentColor" d={d} />
      </Icon>
    )
  }

  return (
    <>
      <Heading mb="4">Default</Heading>
      <Checkbox icon={<CustomIcon />} colorScheme="red">
        Hello world
      </Checkbox>

      <Divider mb="2" mt="2" />

      <Heading mb="4">Indeterminate</Heading>
      <Checkbox
        isChecked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
        icon={<CustomIcon />}
      >
        Parent Checkbox
      </Checkbox>
      <Stack ml="6" mt="2" align="start">
        <Checkbox
          isChecked={checkedItems[0]}
          onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
        >
          Child Checkbox 1
        </Checkbox>
        <Checkbox
          isChecked={checkedItems[1]}
          onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
        >
          Child Checkbox 2
        </Checkbox>
      </Stack>
    </>
  )
}

function WithCustomIconExample() {
  const [checkedItems, setCheckedItems] = React.useState([false, false])
  const allChecked = checkedItems.every(Boolean)
  const isIndeterminate = checkedItems.some(Boolean) && !allChecked
  function CustomIcon(props) {
    const { isIndeterminate, ...rest } = props
    const d = isIndeterminate
      ? "M12,0A12,12,0,1,0,24,12,12.013,12.013,0,0,0,12,0Zm0,19a1.5,1.5,0,1,1,1.5-1.5A1.5,1.5,0,0,1,12,19Zm1.6-6.08a1,1,0,0,0-.6.917,1,1,0,1,1-2,0,3,3,0,0,1,1.8-2.75A2,2,0,1,0,10,9.255a1,1,0,1,1-2,0,4,4,0,1,1,5.6,3.666Z"
      : "M0,12a1.5,1.5,0,0,0,1.5,1.5h8.75a.25.25,0,0,1,.25.25V22.5a1.5,1.5,0,0,0,3,0V13.75a.25.25,0,0,1,.25-.25H22.5a1.5,1.5,0,0,0,0-3H13.75a.25.25,0,0,1-.25-.25V1.5a1.5,1.5,0,0,0-3,0v8.75a.25.25,0,0,1-.25.25H1.5A1.5,1.5,0,0,0,0,12Z"
    return (
      <Icon viewBox="0 0 24 24" {...rest}>
        <path fill="currentColor" d={d} />
      </Icon>
    )
  }
  return (
    <>
      <Heading mb="4">Default</Heading>
      <Checkbox icon={<CustomIcon />} colorScheme="red">
        Hello world
      </Checkbox>
      <Divider mb="2" mt="2" />
      <Heading mb="4">Indeterminate</Heading>
      <Checkbox
        isChecked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
        icon={<CustomIcon />}
      >
        Parent Checkbox
      </Checkbox>
      <Stack ml="6" mt="2" align="start">
        <Checkbox
          isChecked={checkedItems[0]}
          onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
        >
          Child Checkbox 1
        </Checkbox>
        <Checkbox
          isChecked={checkedItems[1]}
          onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
        >
          Child Checkbox 2
        </Checkbox>
      </Stack>
    </>
  )
}

Editable Example

CheckboxGroup#

Chakra exports a CheckboxGroup component to help manage the checked state of its children Checkbox components and conveniently pass a few shared style props to each. See the props table at the bottom of this page for a list of the shared styling props.

Naruto

Sasuke

kakashi

<CheckboxGroup colorScheme="green" defaultValue={["naruto", "kakashi"]}>
  <HStack>
    <Checkbox value="naruto">Naruto</Checkbox>
    <Checkbox value="sasuke">Sasuke</Checkbox>
    <Checkbox value="kakashi">kakashi</Checkbox>
  </HStack>
</CheckboxGroup>

<CheckboxGroup colorScheme="green" defaultValue={["naruto", "kakashi"]}>
  <HStack>
    <Checkbox value="naruto">Naruto</Checkbox>
    <Checkbox value="sasuke">Sasuke</Checkbox>
    <Checkbox value="kakashi">kakashi</Checkbox>
  </HStack>
</CheckboxGroup>

Editable Example

Hooks#

The useCheckbox hook is exported with state and focus management logic for use in creating tailor-made checkbox component for your application

The useCheckboxGroup hook is exported with state management logic for use in creating tailor-made checkbox group component for your application

Props#

Checkbox Props#

Name	Type	Default	Description
id	`string`		The id assigned to input field
name	`string`		The name of the input field in a checkbox (Useful for form submission)
value	`string` or `number`		The value to be used in the checkbox input. This is the value that will be returned on form submission.
colorScheme	`string`		The color of the checkbox when it's checked. This should be one of the color keys in the theme (e.g."green", "red")
defaultIsChecked	`boolean`		If `true`, the checkbox will be initially checked.
isChecked	`boolean`		If `true`, the checkbox will be checked. You'll need to pass `onChange` to update it's value (since it's now controlled)
isIndeterminate	`boolean`		If `true`, the checkbox will be indeterminate. This only affects the icon shown inside checkbox
isFullWidth	`boolean`		If `true`, the checkbox should take up the full width of the parent.
size	`sm`, `md`, `lg`	`md`	The size (width and height) of the checkbox
isDisabled	`boolean`		If `true`, the checkbox will be disabled
icon	`ReactElement`	`CheckboxIcon`	If given, will use this icon instead of the default
isInvalid	`boolean`		If `true`, the checkbox is marked as invalid. Changes style of unchecked state.
children	`React.ReactNode`		The children of the checkbox.
onChange	`function`		Function called when the state of the checkbox changes.
onBlur	`function`		Function called when you blur out of the checkbox.
onFocus	`function`		Function called when the checkbox receive focus.
aria-label	`string`		An accessible label for the checkbox in event there's no visible label or `children` passed
aria-labelledby	`string`		Id that points to the label for the checkbox in event no `children` was passed

CheckboxGroup Props#

Name	Type	Description
value	`Array<Checkbox["value"]>`	The value of the checkbox group
defaultValue	`Array<Checkbox["value"]>`	The initial value of the checkbox group
onChange	`(values: Array<Checkbox["value"]>): void`	The callback fired when any children `Checkbox` is checked or unchecked.
children	`React.ReactNode`	The content of the checkbox group.

Shared Style Props#

The following style props can be set on CheckboxGroup and they will be forwarded to all children Checkbox components.

Name	Type	Default	Description
colorScheme	`string`		The color of the checkbox when it's checked. This should be one of the color keys in the theme (e.g."green", "red").
children	`React.ReactNode`		The content of the checkbox group.
size	`sm`, `md`, `lg`	`md`	The size of the checkbox.
variant	`string`		The `variant` of the checkbox.

Edit this page

Checkbox

.css-12m0k8p{pointer-events:auto;}Import.css-1l2j62r{color:#319795;font-weight:400;outline:none;opacity:0;margin-left:0.375rem;}.css-1l2j62r:focus,.css-1l2j62r[data-focus]{opacity:1;box-shadow:0 0 0 3px rgba(66,153,225,0.6);}#

Usage#

Disabled Checkbox#

Checkbox with custom color#

Checkbox sizes#

Invalid Checkbox#

Changing the spacing#

Changing the icon color and size#

Indeterminate#

Icon#

Default

Indeterminate

CheckboxGroup#

Hooks#

Props#

Checkbox Props#

CheckboxGroup Props#

Shared Style Props#

Import#