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

Name	Type	Description
value	StringOrNumber[]	The value of checkbox group.
isDisabled	boolean	A function to set the boolean value to false.
onChange	(input: EventOrValue) => void	The onChange handler for the checkbox group.
setValue	(state: StringOrNumber[]) => void	A function to set the value of the checkbox group.
getCheckboxProps	(props?: Dict) => Dict	A 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)[]