useCheckbox

Hooks that manage checkbox and checkbox group state, indeterminate logic, and ARIA attributes.

Remember me

basic-demo

Usage#

import { useCheckbox } from '@primereact/headless/checkbox';
 
const { rootProps, inputProps, boxProps, indicatorProps, state } = useCheckbox({
    defaultChecked: true
});
 
return (
    <div {...rootProps}>
        <input {...inputProps} className="sr-only" />
        <div {...boxProps}>{state.checked && <span {...indicatorProps}></span>}</div>
    </div>
);

useCheckbox manages checked/indeterminate state while useCheckboxGroup manages a shared value array — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects (rootProps, inputProps, boxProps, indicatorProps)
Controlled and uncontrolled checked state
Indeterminate state for partial selection patterns
Custom trueValue/falseValue for non-boolean checked values
useCheckboxGroup for managing shared value array across multiple checkboxes
Exposes onChange and updateChange for custom toggle logic

Behavior#

Default Checked#

Use defaultChecked to set the initial checked state.

const checkbox = useCheckbox({ defaultChecked: true });

Controlled#

Use checked and onCheckedChange for full programmatic control.

const [checked, setChecked] = React.useState(true);
const checkbox = useCheckbox({
    checked,
    onCheckedChange: (e) => setChecked(e.checked)
});

The onCheckedChange callback receives { originalEvent, checked } where checked is the new boolean state.

Indeterminate#

Set indeterminate to display a mixed state. When indeterminate, state.checked resolves to false.

const checkbox = useCheckbox({ indeterminate: true });

Disabled#

Set disabled to prevent interaction. inputProps sets disabled on the native input and rootProps adds data-disabled.

const checkbox = useCheckbox({ disabled: true });

Read Only#

Set readOnly to prevent state changes while keeping the checkbox focusable.

const checkbox = useCheckbox({ readOnly: true });

Custom True/False Values#

Use trueValue and falseValue to map checked state to custom values.

const checkbox = useCheckbox({ trueValue: 'yes', falseValue: 'no' });

Checkbox Group#

Use useCheckboxGroup to manage a shared value array. Pass the group's updateChange method to individual checkboxes.

const group = useCheckboxGroup({ defaultValue: ['a', 'b'] });
 
const checkboxA = useCheckbox({
    value: 'a',
    checked: group.state.value?.includes('a'),
    onCheckedChange: (e) => group.updateChange({ ...e, value: 'a' })
});

Controlled Group#

Use value and onValueChange on the group for full programmatic control.

const [value, setValue] = React.useState<unknown[]>(['a']);
const group = useCheckboxGroup({
    value,
    onValueChange: (e) => setValue(e.value)
});

Custom Styling with Data Attributes#

Every prop object includes data-scope="checkbox" and a data-part attribute. State-dependent attributes are added automatically.

[data-scope='checkbox'][data-part='box'] {
    width: 1.25rem;
    height: 1.25rem;
    border: 2px solid #ccc;
    border-radius: 0.25rem;
}
 
[data-scope='checkbox'][data-part='box'][data-checked] {
    background: var(--p-primary-color);
    border-color: var(--p-primary-color);
}
 
[data-scope='checkbox'][data-part='box'][data-indeterminate] {
    background: var(--p-primary-color);
    border-color: var(--p-primary-color);
}
 
[data-scope='checkbox'][data-part='root'][data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
}

API#

useCheckbox#

Name	Type	Default
`checked`	`boolean`	—
When present, it specifies the input's checked state.
`defaultChecked`	`boolean`	—
The default value for the input when not controlled by `checked` and `onCheckedChange` .
`inputId`	`string`	—
Identifier of the underlying input element.
`indeterminate`	`boolean`	`false`
When present, it specifies input state as indeterminate.
`trueValue`	`string` \| `number` \| `boolean`	`true`
Value in checked state.
`falseValue`	`string` \| `number` \| `boolean`	`false`
Value in unchecked state.
`value`	`unknown`	—
Value of the checkbox.
`name`	`string`	—
The name attribute of the input, resolved from group context if available.
`disabled`	`boolean`	`false`
When present, it specifies that the element should be disabled.
`readOnly`	`boolean`	`false`
When present, it specifies that an input field is read-only.
`required`	`boolean`	`false`
When present, it specifies that the element is required.
`tabIndex`	`number`	—
Tab index for keyboard navigation.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`ariaLabelledby`	`string`	—
Establishes relationships between the component and label(s) where its value should be one or more element IDs.
`ariaLabel`	`string`	—
Establishes a string value that labels the component.
`onFocus`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback function that is called when the checkbox is focused.
`onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback function that is called when the checkbox loses focus.
`onCheckedChange`	`(event: useCheckboxChangeEvent) => void`	—
Callback fired when the checkbox's checked state changes.

useCheckboxGroup#

Name	Type	Default
`value`	`unknown[]`	—
Value of the checkbox group.
`defaultValue`	`unknown[]`	—
The default value of the checkbox group.
`onValueChange`	`(event: useCheckboxGroupChangeEvent) => void`	—
Callback fired when the checkboxgroup's value state changes.

Accessibility#

See Checkbox Primitive for WAI-ARIA compliance details and keyboard support.