useCheckbox
useCheckbox is a custom hook used to provide checkbox functionality, as well
as state and focus management to custom checkbox components when using it.
Import
import { useCheckbox } from '@chakra-ui/react'
Return value
The useCheckbox hook returns following props
| Name | Type | Description |
|---|---|---|
state | CheckboxState | An object that contains all props defining the current state of a checkbox. |
getCheckboxProps | PropGetter | A function to get the props of the checkbox. |
getInputProps | PropGetter | A function to get the props of the input field. |
getLabelProps | PropGetter | A function to get the props of the checkbox label. |
htmlProps | {} | An object with all htmlProps. |
Usage
function Example() {
const CustomCheckbox = (props) => {
const { state, getCheckboxProps, getInputProps, getLabelProps, htmlProps } =
useCheckbox(props)
return (
<chakra.label
display='flex'
flexDirection='row'
alignItems='center'
gridColumnGap={2}
maxW='36'
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</Text>
</chakra.label>
)
}
return (
<div>
<CustomCheckbox />
</div>
)
}
Parameters
The useCheckbox hook accepts an object with the following properties:
aria-describedby
aria-describedbystringaria-invalid
aria-invalidtruearia-label
aria-labelDefines the string that labels the checkbox element.
stringaria-labelledby
aria-labelledbyRefers to the id of the element that labels the checkbox element.
stringdefaultChecked
defaultCheckedIf true, the checkbox will be initially checked.
booleanid
idid assigned to input
stringisChecked
isCheckedIf true, the checkbox will be checked.
You'll need to pass onChange to update its value (since it is now controlled)
booleanisDisabled
isDisabledIf true, the checkbox will be disabled
booleanisFocusable
isFocusableIf true and isDisabled is passed, the checkbox will
remain tabbable but not interactive
booleanisIndeterminate
isIndeterminateIf true, the checkbox will be indeterminate.
This only affects the icon shown inside checkbox
and does not modify the isChecked property.
booleanisInvalid
isInvalidIf true, the checkbox is marked as invalid.
Changes style of unchecked state.
booleanisReadOnly
isReadOnlyIf true, the checkbox will be readonly
booleanisRequired
isRequiredIf true, the checkbox input is marked as required,
and required attribute will be added
booleanname
nameThe name of the input field in a checkbox (Useful for form submission).
stringonBlur
onBlurThe callback invoked when the checkbox is blurred (loses focus)
((event: FocusEvent<HTMLInputElement, Element>) => void)onChange
onChangeThe callback invoked when the checked state of the Checkbox changes.
((event: ChangeEvent<HTMLInputElement>) => void)onFocus
onFocusThe callback invoked when the checkbox is focused
((event: FocusEvent<HTMLInputElement, Element>) => void)tabIndex
tabIndexThe tab-index property of the underlying input element.
numbervalue
valueThe value to be used in the checkbox input. This is the value that will be returned on form submission.
string | number