string
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.labeldisplay='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 /><FlexalignItems='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 {...getLabelProps()}>Click me</Text></chakra.label>)}return (<div><CustomCheckbox /></div>)}
Parameters#
The useCheckbox
hook accepts an object with the following properties:
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
defaultChecked
defaultChecked
If true
, the checkbox will be initially checked.
boolean
defaultIsChecked
defaultIsChecked
If true
, the checkbox will be initially checked.
@deprecated Please use the defaultChecked
prop, which mirrors default
React checkbox behavior.
boolean
id
id
id assigned to input
string
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
onBlur
onBlur
The callback invoked when the checkbox is blurred (loses focus)
((event: FocusEvent<HTMLInputElement, Element>) => void)
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)
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