Skip to main content

useCheckboxGroup

useCheckboxGroup is a custom hook that provides all the state management logic for a group of checkboxes.

Import

import { useCheckboxGroup } from '@chakra-ui/react'

Return value

The useCheckboxGroup hook returns following props

NameTypeDescription
valueStringOrNumber[]The value of checkbox group.
isDisabledbooleanA function to set the boolean value to false.
onChange(input: EventOrValue) => voidThe onChange handler for the checkbox group.
setValue(state: StringOrNumber[]) => voidA function to set the value of the checkbox group.
getCheckboxProps(props?: Dict) => DictA function that takes checkbox props returns them with a onChange handler for the checkbox group and the checked state.

Usage

function Example() {
function CustomCheckbox(props) {
const { state, getCheckboxProps, getInputProps, getLabelProps, htmlProps } =
useCheckbox(props)

return (
<chakra.label
display='flex'
flexDirection='row'
alignItems='center'
gridColumnGap={2}
maxW='40'
bg='green.50'
border='1px solid'
borderColor='green.500'
rounded='lg'
px={3}
py={1}
cursor='pointer'
{...htmlProps}
>
<input {...getInputProps()} hidden />
<Flex
alignItems='center'
justifyContent='center'
border='2px solid'
borderColor='green.500'
w={4}
h={4}
{...getCheckboxProps()}
>
{state.isChecked && <Box w={2} h={2} bg='green.500' />}
</Flex>
<Text color="gray.700" {...getLabelProps()}>Click me for {props.value}</Text>
</chakra.label>
)
}

const { value, getCheckboxProps } = useCheckboxGroup({
defaultValue: ['2'],
})

return (
<Stack>
<Text>The selected checkboxes are: {value.sort().join(' and ')}</Text>
<CustomCheckbox {...getCheckboxProps({ value: '1' })} />
<CustomCheckbox {...getCheckboxProps({ value: '2' })} />
<CustomCheckbox {...getCheckboxProps({ value: '3' })} />
</Stack>
)
}

Parameters

The useCheckboxGroup hook accepts an object with the following properties:

defaultValue

Description

The initial value of the checkbox group

Type
(string | number)[]

isDisabled

Description

If true, all wrapped checkbox inputs will be disabled

Type
boolean

isNative

Description

If true, input elements will receive checked attribute instead of isChecked. This assumes, you're using native radio inputs

Type
boolean

onChange

Description

The callback fired when any children Checkbox is checked or unchecked

Type
((value: (string | number)[]) => void)

value

Description

The value of the checkbox group

Type
(string | number)[]