Checkbox

Custom-styled checkbox component with clear visual states. Uses native checkbox input with enhanced styling for better UX and accessibility.

Component Props

Prop	Type	Default	Description
`name`	string	required	Input name attribute
`value`	mixed	1	Input value when checked
`checked`	bool	false	Initial checked state
`disabled`	bool	false	Disabled state
`ariaLabel`	string	null	Accessible label for standalone usage
`class`	string	''	Additional wrapper classes

States

Unchecked

I agree to the terms and conditions

Default unchecked state

Checked

Send me email notifications

Checked state with checkmark

Disabled (Unchecked)

This option is not available

Disabled and unchecked

Disabled (Checked)

Required feature (cannot be changed)

Disabled and checked

Real-World Examples

Terms Agreement

I agree to the Terms of Service and Privacy Policy

Notification Preferences

Email alerts for high-risk areas

SMS alerts for nearby outbreaks

Push notifications

Feature Toggles

Show risk map

Show statistics

Enable dark mode

Standalone (Icon Only)

Item 1

Item 2

Use ariaLabel when checkbox has no visible label

Usage Example

Basic Usage with Label

<x-building-blocks.checkbox name="agree">
    I agree to the terms
</x-building-blocks.checkbox>

Pre-checked

<x-building-blocks.checkbox 
    name="notifications" 
    :checked="true"
>
    Enable notifications
</x-building-blocks.checkbox>

Disabled

<x-building-blocks.checkbox 
    name="required_feature" 
    :checked="true"
    :disabled="true"
>
    Required feature
</x-building-blocks.checkbox>

Standalone (No Label)

<x-building-blocks.checkbox 
    name="select_item" 
    ariaLabel="Select this item"
/>

Key Features

Custom Styling: Beautiful checkmark animation on selection
Native Input: Uses native checkbox for full browser compatibility
Keyboard Accessible: Full keyboard support with Space to toggle
Focus Indicators: Clear focus ring for keyboard navigation
Flexible Labels: Supports inline labels or standalone usage
WCAG 2.1 AA: Fully accessible with proper ARIA support

Best Practices

Do:

Use checkboxes for multiple selections (not mutually exclusive)
Provide clear, concise labels
Use ariaLabel for standalone checkboxes without visible labels
Group related checkboxes with a fieldset and legend
Make the entire label clickable (default behavior)
Use disabled state sparingly and explain why

Don't:

Don't use checkboxes for mutually exclusive options (use radio buttons)
Don't use checkboxes for binary on/off settings (use toggle/switch)
Don't make labels too long (keep them concise)
Don't use checkboxes without labels unless using ariaLabel
Don't pre-check boxes unless there's a clear default

Accessibility Features

Native Checkbox: Uses native input for screen reader compatibility
Keyboard Navigation: Space to toggle, Tab to navigate
Focus Ring: Clear visual indicator for keyboard users
ARIA Labels: Support for aria-label on standalone checkboxes
Clickable Labels: Entire label area is clickable for easier interaction