string
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/react'
Usage#
Basic usage of Checkbox
.
<Checkbox defaultChecked>Checkbox</Checkbox>
Disabled Checkbox#
<Stack spacing={5} direction='row'><Checkbox isDisabled>Checkbox</Checkbox><Checkbox isDisabled defaultChecked>Checkbox</Checkbox></Stack>
Checkbox with custom color#
You can override the color scheme of the Checkbox
to any color key specified
in theme.colors
.
<Stack spacing={5} direction='row'><Checkbox colorScheme='red' defaultChecked>Checkbox</Checkbox><Checkbox colorScheme='green' defaultChecked>Checkbox</Checkbox></Stack>
Checkbox sizes#
Pass the size
prop to change the size of the Checkbox
. Values can be either
sm
, md
or lg
.
<Stack spacing={[1, 5]} direction={['column', 'row']}><Checkbox size='sm' colorScheme='red'>Checkbox</Checkbox><Checkbox size='md' colorScheme='green' defaultChecked>Checkbox</Checkbox><Checkbox size='lg' colorScheme='orange' defaultChecked>Checkbox</Checkbox></Stack>
Invalid Checkbox#
<Checkbox isInvalid>Checkbox</Checkbox>
Changing the spacing#
We added the spacing
prop to customize the spacing between the Checkbox
and
label text.
<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>
Indeterminate#
function IndeterminateExample() {const [checkedItems, setCheckedItems] = React.useState([false, false])const allChecked = checkedItems.every(Boolean)const isIndeterminate = checkedItems.some(Boolean) && !allCheckedreturn (<><CheckboxisChecked={allChecked}isIndeterminate={isIndeterminate}onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}>Parent Checkbox</Checkbox><Stack pl={6} mt={1} spacing={1}><CheckboxisChecked={checkedItems[0]}onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}>Child Checkbox 1</Checkbox><CheckboxisChecked={checkedItems[1]}onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}>Child Checkbox 2</Checkbox></Stack></>)}
Icon#
/*** 1. Create a custom icon that accepts 2 props: `isIndeterminate` and `isChecked`*/function CustomIcon(props) {const { isIndeterminate, isChecked, ...rest } = propsconst 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>)}function CustomCheckbox() {return (<Checkbox icon={<CustomIcon />} colorScheme='cyan'>Hello world</Checkbox>)}render(<CustomCheckbox />)
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.
<CheckboxGroup colorScheme='green' defaultValue={['naruto', 'kakashi']}><Stack spacing={[1, 5]} direction={['column', 'row']}><Checkbox value='naruto'>Naruto</Checkbox><Checkbox value='sasuke'>Sasuke</Checkbox><Checkbox value='kakashi'>kakashi</Checkbox></Stack></CheckboxGroup>
Hooks#
The useCheckbox
hook is exported with state and focus management logic for use
in creating tailor-made checkbox component for your application. Read more about
the useCheckbox
hook here.
The useCheckboxGroup
hook is exported with state management logic for use in
creating tailor-made checkbox group component for your application. Read more
about the useCheckboxGroup
hook
here.
Props#
Checkbox Props#
aria-describedby
aria-describedby
aria-invalid
aria-invalid
true
aria-label
aria-label
Defines the string that labels the checkbox element.
string
aria-labelledby
aria-labelledby
Refers to the id
of the element that labels the checkbox element.
string
colorScheme
colorScheme
"whiteAlpha" | "blackAlpha" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink" | "linkedin" | "facebook" | "messenger" | "whatsapp" | "twitter" | "telegram"
"blue"
defaultIsChecked
defaultIsChecked
If true
, the checkbox will be initially checked.
@deprecated Please use the defaultChecked
prop, which mirrors default
React checkbox behavior.
boolean
icon
icon
The checked icon to use
React.ReactElement
CheckboxIcon
iconColor
iconColor
The color of the checkbox icon when checked or indeterminate
string
iconSize
iconSize
The size of the checkbox icon when checked or indeterminate
string | number
id
id
id assigned to input
string
inputProps
inputProps
Additional props to be forwarded to the input
element
InputHTMLAttributes<HTMLInputElement>
isChecked
isChecked
If true
, the checkbox will be checked.
You'll need to pass onChange
to update its value (since it is now controlled)
boolean
isDisabled
isDisabled
If true
, the checkbox will be disabled
boolean
isFocusable
isFocusable
If true
and isDisabled
is passed, the checkbox will
remain tabbable but not interactive
boolean
isIndeterminate
isIndeterminate
If true
, the checkbox will be indeterminate.
This only affects the icon shown inside checkbox
and does not modify the isChecked property.
boolean
isInvalid
isInvalid
If true
, the checkbox is marked as invalid.
Changes style of unchecked state.
boolean
isReadOnly
isReadOnly
If true
, the checkbox will be readonly
boolean
isRequired
isRequired
If true
, the checkbox input is marked as required,
and required
attribute will be added
boolean
name
name
The name of the input field in a checkbox (Useful for form submission).
string
onChange
onChange
The callback invoked when the checked state of the Checkbox
changes.
((event: ChangeEvent<HTMLInputElement>) => void)
onFocus
onFocus
The callback invoked when the checkbox is focused
((event: FocusEvent<HTMLInputElement, Element>) => void)
size
size
"sm" | "md" | "lg"
"md"
spacing
spacing
The spacing between the checkbox and its label text
SystemProps["marginLeft"]
0.5rem
tabIndex
tabIndex
number
value
value
The value to be used in the checkbox input. This is the value that will be returned on form submission.
string | number
variant
variant
Variants for Checkbox
are not implemented in the default theme. You can extend the theme to implement them.
string
CheckboxGroup Props#
colorScheme
colorScheme
Color Schemes for CheckboxGroup
are not implemented in the default theme. You can extend the theme to implement them.
(string & {})
defaultValue
defaultValue
The initial value of the checkbox group
StringOrNumber[]
isDisabled
isDisabled
If true
, all wrapped checkbox inputs will be disabled
boolean
isNative
isNative
If true
, input elements will receive
checked
attribute instead of isChecked
.
This assumes, you're using native radio inputs
boolean
onChange
onChange
The callback fired when any children Checkbox is checked or unchecked
((value: StringOrNumber[]) => void)
size
size
Sizes for CheckboxGroup
are not implemented in the default theme. You can extend the theme to implement them.
string
value
value
The value of the checkbox group
StringOrNumber[]
variant
variant
Variants for CheckboxGroup
are not implemented in the default theme. You can extend the theme to implement them.
string
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 is 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. |