Checkbox

v1.1.3

Ready for Production

Catalyst Checkbox extends Radix UI's Checkbox primitive with built-in CVA variants, design tokens, and three-state support — giving you a production-ready checkbox with compact sizing for data-dense product interfaces.

Installation

npm install @pmi/catalyst-checkbox

import { CheckboxRoot, CheckboxIndicator } from '@pmi/catalyst-checkbox';

Variants

Checked

Unchecked

Indeterminate

Sizes

Three compact sizes are available, optimized for data-dense interfaces: sm (20 px), md (24 px, default), and lg (28 px).

Common Patterns

Danger State

Use the danger prop to indicate validation errors or required selections.

Disabled State

With Label

Pair checkboxes with a Label component using aria-labelledby for accessible association.

With Helper Text

Combine a label and helper text to provide additional context or validation messages.

API Reference

Checkbox is a compound component built on Radix UI primitives. The sections below summarize the shared API surface for each part of the component.

CheckboxRoot

The interactive checkbox button. Accepts all standard Radix Checkbox Root props and forwards ref.

CheckboxIndicator

Container for the checkbox icon (checkmark or minus). Renders only when the checkbox is checked or indeterminate. Accepts all standard Radix Checkbox Indicator props and forwards ref.

Accessibility

Keyboard Interactions

ARIA

• The component uses role="checkbox" and sets aria-checked to "true", "false", or "mixed" for the indeterminate state — inherited from Radix UI.
• Always pair a checkbox with a visible label. Use aria-labelledby pointing to the label's id, or wrap both in a native <label>.
• When using the danger prop, pair it with a HelperText component that describes the error so screen readers announce the error context.

See the Radix Checkbox accessibility docs for inherited baseline behavior.

Choosing the Right Component

Use Checkbox when users need to independently toggle one or more options on or off. Reach for a different primitive when:

Related

• Label
• Helper Text
• Radio Group
• Switch