Design System Beacon

Checkbox

Checkboxes allow users to select one or more options from a set. Use checkboxes when users need to make multiple selections or toggle a single option.

Overview

Checkboxes are form controls that allow users to select one or more options from a set. They provide a clear visual indication of selection state and support three states: unchecked, checked, and indeterminate.

All checkbox styles are built using design tokens, ensuring consistency across themes and hues. Use the interactive playground below to explore all available combinations.

Interactive Playground

Use the controls to customize the checkbox and see how it looks in real-time. Toggle between themes and hues to see how checkboxes adapt to different contexts.

Color

Status

Checked

Label

Label Text

Checkbox

<Checkbox />

Anatomy

A checkbox consists of a box container and an optional label. The box displays different visual states based on selection.

Checkbox

Checkbox Box20px × 20px, border-radius: 4px

IconCheckIcon (when checked)

LabelOptional text label

Variants & States

Checkboxes come in different states to fit various use cases. Each state provides clear visual feedback for user interaction.

Unchecked - Default

Default when unselected. Transparent background with border.

Checkbox

Unchecked - Hovered

Hover shows visual feedback on pointer over the checkbox.

Checkbox

Unchecked - Focused

Focus indicates keyboard navigation with a visible focus ring.

Checkbox

Unchecked - Pressed

Pressed gives feedback when the checkbox is clicked or pressed.

Checkbox

Unchecked - Disabled

Disabled blocks interaction with reduced opacity and colors.

Checkbox

Checked - Default

Selected uses primary background with a white checkmark.

Checkbox

Checked - Hovered

Checked hover uses a darker primary background.

Checkbox

Checked - Focused

Checked focus shows a primary-colored focus ring.

Checkbox

Checked - Pressed

Checked pressed uses a darker primary background.

Checkbox

Checked - Disabled

Checked disabled shows reduced opacity and disabled primary.

Checkbox

Usage Guidelines

Use checkboxes for multiple selections from a list.
Use checkboxes to toggle a single option on or off.
Provide clear, descriptive labels for each checkbox.
Group related checkboxes together visually.
Ensure sufficient spacing between checkboxes and labels.
Provide clear visual feedback for all interactive states (hover, focus, checked).

Don't

Don't use checkboxes for mutually exclusive options (use radio buttons instead).
Don't use checkboxes for immediate actions (use buttons instead).
Don't nest checkboxes too deeply in hierarchical structures.
Don't use checkboxes without labels or with unclear labels.
Don't disable checkboxes without explaining why.
Don't use indeterminate state for single-level checkbox lists.

Accessibility

Always associate checkboxes with labels using proper HTML structure or ARIA attributes.
Ensure sufficient color contrast between checkbox states and backgrounds.
Provide keyboard navigation support (Space to toggle, Tab to navigate).
Ensure checkboxes are large enough to be easily clickable (minimum 20px).
Provide clear visual feedback for all interactive states (hover, focus, checked).
Use semantic HTML (`<input type="checkbox">` or proper ARIA roles).

API Reference

Checkbox component props and types.

CheckboxProps

interface CheckboxProps {
  checked?: boolean;
  disabled?: boolean;
  status?: "default" | "hovered" | "focused" | "pressed" | "disabled";
  label?: string;
  showLabel?: boolean;
  onChange?: (checked: boolean) => void;
}

Props

checked

boolean

false

Whether the checkbox is checked. When true, displays checkmark icon.

status

"default" | "hovered" | "focused" | "pressed" | "disabled"

"default"

Interactive state of the checkbox. Controls visual styling for different interaction states.

label

string

"Checkbox"

Text label displayed next to the checkbox.

showLabel

boolean

false

Whether to display the label text. When false, label is only used for accessibility.

disabled

boolean

false

Whether the checkbox is disabled. When true, prevents interaction and applies disabled styling.

onChange

(checked: boolean) => void

—

Callback function called when checkbox state changes.

Usage Examples

Copyable code snippets for common checkbox use cases.

Basic Checkbox

import { Checkbox } from 'beacon-ui';

<Checkbox />

Checkbox with Label

import { Checkbox } from 'beacon-ui';

<Checkbox 
  label="Accept terms and conditions"
  showLabel
/>

Checked Checkbox

import { Checkbox } from 'beacon-ui';

<Checkbox 
  checked
  label="I agree"
  showLabel
/>

Disabled Checkbox

import { Checkbox } from 'beacon-ui';

<Checkbox 
  checked
  disabled
  label="Cannot change"
  showLabel
/>

Checkbox with States

import { Checkbox } from 'beacon-ui';

<Checkbox label="Default" status="default" showLabel />
<Checkbox label="Hovered" status="hovered" showLabel />
<Checkbox label="Focused" status="focused" showLabel />
<Checkbox label="Pressed" status="pressed" showLabel />
<Checkbox label="Disabled" disabled showLabel />

Checkbox Group

import { Checkbox } from 'beacon-ui';

<div>
  <Checkbox label="Option 1" showLabel />
  <Checkbox label="Option 2" checked showLabel />
  <Checkbox label="Option 3" showLabel />
</div>