Checkboxes
Use checkboxes when users need to select one or more options from a list, or to toggle a single option on or off.
Default Checkboxes
Checkboxes use a large 32x32px touch target for accessibility and ease of use on mobile devices. Built with Radix UI primitives for full accessibility.
import * as Checkbox from '@radix-ui/react-checkbox';
import { Check } from 'lucide-react';
<fieldset className="form-fieldset">
<legend className="form-legend">Which types of waste do you transport?</legend>
<div className="radix-checkbox-group">
<div className="radix-checkbox-item">
<Checkbox.Root className="radix-checkbox" id="waste-1">
<Checkbox.Indicator className="radix-checkbox-indicator">
<Check size={18} strokeWidth={3} />
</Checkbox.Indicator>
</Checkbox.Root>
<label className="radix-checkbox-label" htmlFor="waste-1">
Waste from animal carcasses
</label>
</div>
...
</div>
</fieldset>With Hint Text
Use hint text in the legend to provide additional context.
<fieldset className="form-fieldset">
<legend className="form-legend">
What is your nationality?
<span className="form-legend-hint">Select all that apply.</span>
</legend>
<div className="radix-checkbox-group">
...
</div>
</fieldset>Pre-selected Checkboxes
Only pre-select checkboxes when there's a strong, user-centred reason to do so.
<Checkbox.Root className="radix-checkbox" id="pref-1" defaultChecked>
...
</Checkbox.Root>Single Checkbox (Toggle)
Use a single checkbox for binary choices or accepting terms.
<div className="radix-checkbox-item">
<Checkbox.Root className="radix-checkbox" id="terms">
<Checkbox.Indicator className="radix-checkbox-indicator">
<Check size={18} strokeWidth={3} />
</Checkbox.Indicator>
</Checkbox.Root>
<label className="radix-checkbox-label" htmlFor="terms">
I accept the terms and conditions
</label>
</div>Checkboxes with Links
When checkbox labels contain links, use the standard label class. For labels that are only a link, use radix-checkbox-label-link.
{/* Mixed text and link - use standard label */}
<label className="radix-checkbox-label" htmlFor="terms-link">
I accept the <a href="#">terms and conditions</a>
</label>
{/* Link-only - use -link variant for alignment */}
<label className="radix-checkbox-label-link" htmlFor="privacy-link">
<a href="#">Privacy policy</a>
</label>Error State
<fieldset className="form-fieldset form-group-error">
<legend className="form-legend">Do you agree to the terms?</legend>
<span className="form-error-message">Select an option</span>
<div className="radix-checkbox-group">
...
</div>
</fieldset>Usage Guidelines
Do
- Use checkboxes when users can select multiple options
- Use a single checkbox for binary on/off choices
- List options in a logical order (alphabetical, by frequency, etc.)
- Use a fieldset and legend to group related checkboxes
Don't
- Don't use checkboxes when only one option can be selected (use radios)
- Don't pre-select options unless there's a good reason
- Don't use negative language ("Don't send me emails")
Accessibility
- Built with Radix UI primitives for full WAI-ARIA compliance
- Group related checkboxes in a fieldset with a legend
- Large touch targets (32x32px) for mobile accessibility
- Clear focus states with yellow outline
- Labels are clickable to check/uncheck
- Keyboard navigation: Space to toggle, Tab to move between
CSS Classes
/* Radix checkbox container */
.radix-checkbox-group { }
.radix-checkbox-item { }
/* Checkbox button */
.radix-checkbox { }
.radix-checkbox-indicator { }
/* Labels */
.radix-checkbox-label { }
.radix-checkbox-label-link { } /* For link-only labels (-1px adjustment) */
/* Fieldset grouping */
.form-fieldset { }
.form-legend { }
.form-legend-hint { }
/* Error state */
.form-group-error { }
.form-error-message { }Installation
npm install @radix-ui/react-checkbox lucide-react