Switchalternative
Use Switch for immediate-effect settingsCheckbox
Binary toggle for form fields. Use for options that require explicit submission, unlike Switch which takes effect immediately.
Setup
import { Checkbox } from '@fragments-sdk/ui';Examples
Default
Basic checkbox with label
Loading preview...
With Helper Text
Checkbox with helper text
Loading preview...
Checked
Pre-checked checkbox
Loading preview...
Indeterminate
Partial selection state
Loading preview...
Sizes
Available size options
Loading preview...
Disabled
Non-interactive states
Loading preview...
Custom Styling Targets
Use explicit class targets for control vs content styling
Loading preview...
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 |
readOnly | boolean | false | Whether the checkbox cannot be changed by the user |
required | boolean | false | Whether the checkbox is required |
size | enumsmmdlg | md | Checkbox size |
variant | enumdefaultcard | default | Visual variant. 'default' is the inline checkbox, 'card' renders as a full-width clickable card 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 |
form | string | Not set | ID of the form that owns the hidden input |
value | string | Not set | Value attribute for form submission |
uncheckedValue | string | Not set | Value submitted when unchecked |
inputRef | union | Not set | Ref to the hidden input element |
parent | boolean | Not set | Whether this checkbox controls child checkboxes in a checkbox group |
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 |
Usage Guidelines
When to use
- Form fields requiring explicit submission
- Multi-select from a list of options
- Terms and conditions acceptance
- Filter or preference checklists
When not to use
- Immediate effect settings (use Switch)
- Single selection from options (use RadioGroup)
- Selecting from many options (use Select)
Best practices
- Always include a visible label
- Use helperText for additional context when needed
- Group related checkboxes visually
- Use indeterminate state for parent/child relationships
Accessibility
- Proper label association
- Keyboard accessible (Space to toggle)
- Visible focus indicator
- Indeterminate state properly announced