useCheckbox

Usage#

import { useCheckbox } from '@primereact/headless/checkbox';

const { rootProps, inputProps, boxProps, indicatorProps, state } = useCheckbox({
    defaultChecked: true
});
 
<div {...rootProps}>
    <input {...inputProps} className="sr-only" />
    <div {...boxProps}>{state.checked && <span {...indicatorProps}></span>}</div>
</div>;

useCheckbox manages checked and indeterminate state for a single checkbox, while useCheckboxGroup manages a shared value array across many. See Primitive for a component-based API.

Features#

• Composable parts — spreads props onto root, input, box, and indicator elements so the visual layer is fully yours
• Tri-state semantics — supports checked, unchecked, and indeterminate mixed state for parent/child selection patterns
• Custom value mapping — trueValue and falseValue let checked state represent non-boolean values
• Group coordination — useCheckboxGroup maintains a shared value array and exposes updateChange for child checkboxes
• Controlled or uncontrolled — drive via checked/onCheckedChange or let the hook own state from defaultChecked

Working with callbacks#

Controlled checkbox#

Pass checked and onCheckedChange to own the state externally — needed for validation, async toggles, or parent-driven UI.

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

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

Indeterminate parent#

Render a "select all" checkbox that reflects partial children selection by computing indeterminate from child state.

const allChecked = items.every((i) => i.selected);
const someChecked = items.some((i) => i.selected);
 
useCheckbox({
    checked: allChecked,
    indeterminate: someChecked && !allChecked,
    onCheckedChange: (e) => toggleAll(e.checked)
});

Custom values#

Use trueValue/falseValue when the checkbox represents a non-boolean field such as 'yes'/'no'.

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

Group with shared value#

useCheckboxGroup owns the array; each checkbox derives its checked and forwards its event through the group's updateChange.

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#

Lift the group value into state to react to changes or persist selection.

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

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#

useCheckboxGroup#

Accessibility#

Space toggles the checked state while focused. Use indeterminate for tri-state checkboxes. See Primitive for full WAI-ARIA compliance details.