Checkbox
Boolean selection controls for choosing one or multiple options from a set. Supports checked, unchecked, and indeterminate states with convex physics for tactile elevation on interaction. Use checkboxes when users can select zero, one, or multiple items independently.
Physics Checkboxes use convex shadows to create depth. On hover, the checkbox elevates slightly (-1px) with expanded shadow. The check icon scales in with a spring animation on selection.
Examples
Basic Checkbox
Simple checkbox with a label for basic boolean selection.
<Checkbox label="I agree to the terms and conditions" />Controlled Checkbox
Manage checkbox state with React state for controlled behavior.
const [checked, setChecked] = useState(false);
<Checkbox
label="Subscribe to newsletter"
checked={checked}
onCheckedChange={setChecked}
/>Default Checked
Start with the checkbox already selected using uncontrolled mode.
<Checkbox label="Receive product updates" defaultChecked />Indeterminate State
Use indeterminate to show a partially-selected parent when some but not all children are selected.
<Checkbox
label="Select all items"
indeterminate={someSelected && !allSelected}
checked={allSelected}
onCheckedChange={handleSelectAll}
/>With Helper Text
Add additional context or instructions below the checkbox.
<Checkbox
label="Enable two-factor authentication"
helperText="We'll send a verification code to your phone each time you sign in"
/>Required Field
Mark the checkbox as required with a visual indicator.
<Checkbox label="Accept privacy policy" required />Error State
Display validation errors with status and helper text.
<Checkbox
label="Accept terms of service"
variant="error"
helperText="You must accept the terms to continue"
/>Confirmed Selection
Show a pre-checked checkbox for confirmed settings.
<Checkbox
label="Email preferences saved"
defaultChecked
helperText="Your preferences have been saved"
/>Disabled States
Disable interaction for readonly or unavailable options.
<Checkbox label="Disabled unchecked" disabled />
<Checkbox label="Disabled checked" disabled defaultChecked />Variant Styling
Use the variant prop to apply visual emphasis for error states.
<Checkbox label="Default variant" />
<Checkbox label="Error variant" variant="error" />All Sizes Comparison
Compare all three sizes for different density requirements.
<Checkbox label="Small" size="sm" />
<Checkbox label="Medium" size="md" />
<Checkbox label="Large" size="lg" />CheckboxGroup with Options
Use CheckboxGroup to manage multiple selections with an options array.
<CheckboxGroup
label="Select your interests"
options={[
{ value: 'tech', label: 'Technology' },
{ value: 'design', label: 'Design' },
{ value: 'business', label: 'Business' },
{ value: 'science', label: 'Science' },
]}
value={groupValue}
onChange={setGroupValue}
/>Horizontal CheckboxGroup
Arrange checkboxes horizontally for compact layouts.
<CheckboxGroup
label="File formats to export"
orientation="horizontal"
options={[
{ value: 'pdf', label: 'PDF' },
{ value: 'csv', label: 'CSV' },
{ value: 'xlsx', label: 'Excel' },
]}
defaultValue={['pdf']}
/>CheckboxGroup with Disabled Options
Disable specific options within a group while keeping others interactive.
<CheckboxGroup
label="Subscription features"
options={[
{ value: 'email', label: 'Email notifications' },
{ value: 'sms', label: 'SMS alerts', disabled: true, helperText: 'Requires phone verification' },
{ value: 'push', label: 'Push notifications' },
]}
defaultValue={['email']}
/>CheckboxGroup with Error
Show validation errors for the entire group.
<CheckboxGroup
label="Select at least one option"
required
status="error"
helperText="Please select at least one communication preference"
options={[
{ value: 'email', label: 'Email' },
{ value: 'phone', label: 'Phone' },
{ value: 'mail', label: 'Mail' },
]}
/>Form Usage Pattern
Common pattern for terms acceptance in forms with validation.
<Checkbox
label={<span>I agree to the <a href="#">Terms of Service</a></span>}
required
/>
<Checkbox
label={<span>I have read the <a href="#">Privacy Policy</a></span>}
required
/>
<Checkbox
label="Send me promotional emails (optional)"
/>Best Practices
Do
- Use clear, action-oriented labels
- Provide helper text for complex options
- Use indeterminate for parent checkboxes
- Group related checkboxes together
- Mark required fields clearly
Don't
- Don't use checkboxes for mutually exclusive options (use Radio instead)
- Don't use negative labels ("Don't send emails")
- Don't hide important options in collapsed groups
- Don't overload with too many options (consider progressive disclosure)
Checkbox Props
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | - | Controlled checked state |
defaultChecked | boolean | false | Initial checked state (uncontrolled) |
indeterminate | boolean | false | Show indeterminate (minus) state |
onChange | (e: ChangeEvent) => void | - | Native change event handler |
onCheckedChange | (checked: boolean) => void | - | Convenience handler with boolean value |
label | ReactNode | - | Label content |
helperText | string | - | Helper text below checkbox |
variant | 'default' | 'error' | 'default' | Visual variant (error styling) |
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | Checkbox size |
required | boolean | false | Mark as required field |
disabled | boolean | false | Disable the checkbox |
Accessibility
- Keyboard: Space to toggle, Tab to navigate between checkboxes
- ARIA: Uses native checkbox with
aria-checked(including "mixed" for indeterminate) - Focus: Visible focus ring for keyboard navigation
- Labels: Always associate labels with checkboxes via
htmlFor - Error states: Uses
aria-invalidandaria-describedbyfor helper text