React Checkbox component

Preview

<StatefulCheckbox label="Accept terms and conditions" />

Usage

Use when

Choices that apply only once the form is submitted
Picking several items from a list
Accepting terms
Filter and preference lists

Avoid when

Settings that apply instantly (use Switch)
One choice from a few (use RadioGroup)
Many options (use Select)

Implementation notes

Always show a label
Add helperText when the consequence is not obvious
Keep related boxes together
Use indeterminate for a parent whose children are partly checked
Pair invalid with an errorMessage; the danger edge alone is colour only

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

With Helper Text

Second line spells out what opting in does.

<StatefulCheckbox
  label="Email notifications"
  helperText="Receive email updates about your account activity"
/>

Checked

Starts on.

<StatefulCheckbox defaultChecked label="Subscribe to newsletter" />

Indeterminate

A dash on the parent means only some children are on.

<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
  <Checkbox indeterminate label="Select all" />
  <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>
    <StatefulCheckbox defaultChecked label="Option 1" />
    <StatefulCheckbox label="Option 2" />
    <StatefulCheckbox defaultChecked label="Option 3" />

Disabled

Locked in both positions, on and off.

<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
  <Checkbox disabled label="Disabled unchecked" />
  <Checkbox disabled checked label="Disabled checked" />
</div>

Invalid

A danger edge on the box and a message with an icon under the label.

<Checkbox
  label="I accept the terms"
  invalid
  errorMessage="Accept the terms to continue."
/>

Outline Card

The whole card picks; checked turns its hairline into the selection ring.

<StatefulCheckbox
  variant="outline"
  label="Weekly summary"
  helperText="One email on Monday morning."
/>

API reference

Component props
Prop	Type	Default	Description
`aria-describedby`	`string \| undefined`	Not set	Accessible described-by relationship
`aria-label`	`string \| undefined`	Not set	Accessible label when there is no visible label
`aria-labelledby`	`string \| undefined`	Not set	Accessible labelled-by relationship when there is no visible label
`checked`	`boolean \| undefined`	Not set	Controlled checked state
`defaultChecked`	`boolean \| undefined`	Not set	Default checked state (uncontrolled)
`disabled`	`boolean \| undefined`	`false`	Disable the checkbox
`errorMessage`	`React.ReactNode`	Not set	Message shown with a warning icon under the label while invalid; wired to aria-describedby
`form`	`string \| undefined`	Not set	ID of the form that owns the hidden input
`helperText`	`string \| undefined`	Not set	Helper text shown below the label
`id`	`string \| undefined`	Not set	ID for the checkbox input
`indeterminate`	`boolean \| undefined`	`false`	Indeterminate state (partial selection)
`inputRef`	`React.Ref<HTMLInputElement> \| undefined`	Not set	Ref to the hidden input element
`invalid`	`boolean \| undefined`	`false`	The value fails validation: danger edge on the box and errorMessage under the label
`label`	`string \| undefined`	Not set	Label text
`name`	`string \| undefined`	Not set	Name attribute for form submission
`onCheckedChange`	`((checked: boolean) => void) \| undefined`	Not set	Called with the next checked state when the user toggles the checkbox
`parent`	`boolean \| undefined`	Not set	Whether this checkbox controls child checkboxes in a checkbox group
`readOnly`	`boolean \| undefined`	`false`	The checkbox cannot be changed; band fill and a dashed edge
`required`	`boolean \| undefined`	`false`	Whether the checkbox is required
`uncheckedValue`	`string \| undefined`	Not set	Value submitted when unchecked
`value`	`string \| undefined`	Not set	Value attribute for form submission
`variant`	`"outline" \| undefinedoutline`	Not set	Chrome. Omit for the inline checkbox beside its label; 'outline' renders a full-width choice card (surface, hairline, surface radius) whose hairline turns into the selection ring when checked.

Accessibility

Label is tied to the box
Space toggles it
Focus ring stays visible
Indeterminate is announced as mixed
The error message is wired to aria-describedby and carries an icon and words

Standards references

SwitchalternativeUse Switch for immediate-effect settings
InputsiblingCheckbox handles boolean; Input handles text

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.