Use checkbox when selecting one option should not change other options.
Checkbox
Boolean control for independent selections with optional indeterminate state.
- .source-checkbox-root Click target wrapping control and copy
- .source-checkbox-control Visual checkbox box
- .source-checkbox-input Native checkbox input (visually hidden)
- .source-checkbox-icon Checkmark or indeterminate dash icon
- .source-checkbox-content Label and hint text
States
StateAppearance
UncheckedSurface background with neutral border.
CheckedSemantic palette fill and visible icon.
IndeterminateDash icon shown for mixed selection state.
FocusFocus-visible ring around control.
DisabledMuted opacity and not-allowed cursor.
Design intent
Checkbox handles independent selections where each option stands on its own and checking one does not uncheck another. When options are mutually exclusive, use Radio instead. When the choice toggles a single setting with immediate effect, Switch is a better fit.
When to use
Do
Write labels that can be understood without extra context.
Use indeterminate state when a parent option reflects mixed child selection.
Don't
Do not use checkbox for mutually exclusive options. Use Radio instead.
Avoid verbose copy that makes scanning and tapping difficult.
Do not separate visual control from clickable label. Keep one large hit target.
Palette
Default palette is accent. Switch palette to success, warning, danger, or info only when the semantic meaning is clear in context.
Designer checklist
- Each checkbox has a visible text label. No icon-only checkboxes.
- Indeterminate state is only used for parent selection summaries, not as a third value.
- Error state adds text, not only a color change.
- Minimum 44px touch target on mobile.
Checkbox props
PropTypeDefaultDescription
requiredbooleanfalseShows
* after label and sets the native required attribute.checked / defaultCheckedbooleanfalseControlled or uncontrolled checked state.
indeterminatebooleanfalseShows mixed-state dash icon.
labelReactNodenullMain label next to control.
hintstringnullSecondary text under label.
paletteneutral | accent | success | warning | danger | infoaccentChecked state color palette.
Basic usage
import { Checkbox } from '@pierredelattre/source-react';
<Checkbox
name="terms"
label="I agree to the terms"
checked={agreed}
onChange={(e) => setAgreed(e.target.checked)}
/>Indeterminate usage
<Checkbox
label="Select all"
checked={allSelected}
indeterminate={someSelected && !allSelected}
onChange={toggleAll}
/>Component tokens
TokenDefault
--source-checkbox-size1rem
--source-checkbox-bg-checked--source-color-accent
--source-checkbox-focus-color--source-color-accent
ARIA attributes
AttributePurpose
type="checkbox"Uses native checkbox semantics.
indeterminateSet programmatically on input element for mixed state.
Keyboard support
KeyBehavior
TabMoves focus to control.
SpaceToggles checked state.