Checkbox | Fragments

Preview

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

Installation

npx @usefragments/cli add checkbox

Writes src/fragments/ui/components/Checkbox plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

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" />

Sizes

Three box sizes: sm, md, lg.

<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
  <StatefulCheckbox size="sm" label="Small checkbox" />
  <StatefulCheckbox size="md" label="Medium checkbox" />
  <StatefulCheckbox size="lg" label="Large checkbox" />
</div>

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>

Custom Styling Targets

controlClassName styles the box, contentClassName the text.

<Checkbox
  label="Styled checkbox"
  helperText="Control and content wrappers can be targeted independently"
  controlClassName="demo-checkbox-control"
  contentClassName="demo-checkbox-content"
/>

API

Component props
Prop	Type	Default	Description
`checked`	`boolean`	Not set	Controlled checked state
`defaultChecked`	`boolean`	Not set	Default checked state (uncontrolled)
`onCheckedChange`	`function`	Not set	Called when checked state changes
`onChange`	`function`	Not set	Alias for onCheckedChange: (checked: boolean) => void
`indeterminate`	`boolean`	`false`	Indeterminate state (partial selection)
`disabled`	`boolean`	`false`	Disable the checkbox
`required`	`boolean`	`false`	Whether the checkbox is required
`size`	`enumsmmdlg`	`"md"`	Checkbox size
`variant`	`enumoutline`	Not set	Chrome. Omit for the inline checkbox beside its label; 'outline' renders a full-width bordered surface with the checkbox tucked inside.
`label`	`string`	Not set	Label text
`helperText`	`string`	Not set	Helper text shown below the label (preferred)
`description`	`string`	Not set	Deprecated alias for helperText
`name`	`string`	Not set	Name attribute for form submission
`value`	`string`	Not set	Value attribute for form submission
`id`	`string`	Not set	ID for the checkbox input
`controlClassName`	`string`	Not set	Class name for the checkbox control element (stable styling target)
`contentClassName`	`string`	Not set	Class name for the label/description content wrapper
`aria-label`	`string`	Not set	Accessible label for icon-only mode
`aria-labelledby`	`string`	Not set	Accessible labelled-by relationship for icon-only mode
`aria-describedby`	`string`	Not set	Accessible described-by relationship
`form`	`string`	Not set	ID of the form that owns the hidden input
`inputRef`	`union`	Not set	Ref to the hidden input element
`parent`	`boolean`	Not set	Whether this checkbox controls child checkboxes in a checkbox group
`readOnly`	`boolean`	`false`	Whether the checkbox cannot be changed by the user
`uncheckedValue`	`string`	Not set	Value submitted when unchecked

Accessibility

Label is tied to the box
Space toggles it
Focus ring stays visible
Indeterminate is announced as mixed

Standards

Guidance

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)

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

Next steps

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