Checkbox

An unstyled, accessible checkbox component with compound composition and group support.

Build fully custom checkbox controls with complete control over layout and styling.

Remember me

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Checkbox with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with three sub-components: Root, Box, Indicator
CheckboxGroup for managing shared value array across multiple checkboxes
Indeterminate state for select-all / partial selection patterns

Usage#

import { Checkbox } from 'primereact/checkbox';
import { CheckboxGroup } from 'primereact/checkboxgroup';

<Checkbox.Root>
    <Checkbox.Box>
        <Checkbox.Indicator />
    </Checkbox.Box>
</Checkbox.Root>
 
<CheckboxGroup>
    <Checkbox.Root value="a">
        <Checkbox.Box>
            <Checkbox.Indicator />
        </Checkbox.Box>
    </Checkbox.Root>
    <Checkbox.Root value="b">
        <Checkbox.Box>
            <Checkbox.Indicator />
        </Checkbox.Box>
    </Checkbox.Root>
</CheckboxGroup>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Checkbox.Root as="label">
    <Checkbox.Box as="span">
        <Checkbox.Indicator as="div" />
    </Checkbox.Box>
</Checkbox.Root>

Default elements: Root=div, Box=div, Indicator=span.

Render Function Children#

Checkbox.Box and Checkbox.Indicator accept a render function as children, providing access to the component instance.

<Checkbox.Box>{(instance) => <span>{instance.checkbox?.state.checked ? '✓' : ''}</span>}</Checkbox.Box>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

Accounting

Marketing

Production

Research

/* Select a part to see its CSS selector for custom styling */

API#

CheckboxRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CheckboxRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CheckboxRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CheckboxRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CheckboxRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CheckboxRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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` .
`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.
`tabIndex`	`number`	—
Tab index for keyboard navigation.
`value`	`unknown`	—
Value of the checkbox.
`name`	`string`	—
The name of the checkbox.
`size`	`"small"` \| `"large"` \| `"normal"`	—
Defines the size of the checkbox.
`variant`	`"outlined"` \| `"filled"`	—
Specifies the input variant of the component.
`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.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`inputId`	`string`	—
Identifier of the underlying input element.
`inputStyle`	`CSSProperties`	—
Inline style of the input field.
`inputClassName`	`string`	—
Style class of the input field.
`ariaLabel`	`string`	—
Establishes a string value that labels the component.
`ariaLabelledby`	`string`	—
Establishes relationships between the component and label(s) where its value should be one or more element IDs.
`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: CheckboxRootChangeEvent) => void`	—
Callback fired when the checkbox's checked state changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"checkbox"`
`data-part`	`"root"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-indeterminate`	Present when indeterminate

Defines passthrough(pt) options of CheckboxRoot component.

label	type	description
root	CheckboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
input	CheckboxRootPassThroughType<InputHTMLAttributes<HTMLInputElement>>	Used to pass attributes to the input's DOM element.
box	CheckboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the box's DOM element.
indicator	CheckboxRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the indicator's DOM element.

CheckboxBox#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CheckboxBoxInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CheckboxBoxInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CheckboxBoxInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CheckboxBoxPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CheckboxBoxInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"checkbox"`
`data-part`	`"box"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-indeterminate`	Present when indeterminate

Defines passthrough(pt) options of CheckboxBox component.

label	type	description
root	CheckboxBoxPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CheckboxIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CheckboxIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CheckboxIndicatorInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CheckboxIndicatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CheckboxIndicatorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CheckboxIndicatorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`match`	`"checked"` \| `"indeterminate"` \| `"unchecked"` \| `"always"`	—
Determines the visibility of the indicator based on the state of the checkbox. Valid values are: - "checked": Indicator is visible when the checkbox is checked. - "unchecked": Indicator is visible when the checkbox is unchecked. - "indeterminate": Indicator is visible when the checkbox is in an indeterminate state. - "always": Indicator is always visible.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"checkbox"`
`data-part`	`"indicator"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-indeterminate`	Present when indeterminate

Defines passthrough(pt) options of CheckboxIndicator component.

label	type	description
root	CheckboxIndicatorPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

CheckboxGroup#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CheckboxGroupInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CheckboxGroupInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CheckboxGroupInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CheckboxGroupPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CheckboxGroupInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`value`	`unknown[]`	—
Value of the checkbox group.
`defaultValue`	`unknown[]`	—
The default value of the checkbox group.
`name`	`string`	—
The name of the checkboxes.
`disabled`	`boolean`	`false`
When present, it specifies that the checkbox group should be disabled.
`invalid`	`boolean`	`false`
When present, it specifies that the checkbox group is invalid.
`onValueChange`	`(event: CheckboxGroupChangeEvent) => void`	—
Callback fired when the checkboxgroup's value state changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"checkboxgroup"`
`data-part`	`"root"`

Accessibility#

Checkbox.Root renders a hidden native <input type="checkbox"> that is announced as a checkbox by assistive technologies. The input reflects checked state via aria-checked and uses aria-checked="mixed" for indeterminate state. Provide an accessible name with aria-label, aria-labelledby, or an associated <label> element using inputId.

In a CheckboxGroup, each checkbox is announced individually. Associate labels with inputId + <label htmlFor> or provide aria-label / aria-labelledby on each Checkbox.Root.

Keyboard Support#

Key	Function
`tab`	Moves focus to the next checkbox.
`space`	Toggles checked or unchecked state.