Checkbox

Overview:

The Checkbox component is a binary input control that allows users to select or deselect individual options. It supports multiple independent selections within a group and provides clear visual feedback across interaction states, sizes, and semantic styles.

---

Usage Guidelines:

Use checkboxes for binary choices where users may select one or more options independently.

When to use

• Multi-select lists (filters, preferences, settings)

• Single opt-in actions (e.g., “Agree to terms”)

• Optional features or configurations

When not to use

• Mutually exclusive choices (use Radio instead)

• Actions that trigger immediate navigation or submission

Best practices

• Always pair with a clear, descriptive label

• Use consistent styles within the same group

• Choose style based on semantic intent:

  • cta → primary or emphasized selections

  • grey → default, neutral form selections

  • alert → use style only to represent an error state

    • Not for emphasis or primary actions

    • Only shown when validation fails or user attention is required

---

Component Properties:

style (enum)

Options: grey, cta, alert Purpose: Controls the visual treatment and semantic emphasis of the checkbox. Usage:

• grey → standard form inputs

• cta → primary or highlighted selections

• alert → error state only

Context: For checkboxes (and radio buttons), alert is reserved exclusively for validation errors or invalid states to help notify users of an issue

---

status (enum)

Options: default, hover, focus, active Purpose: Represents the interactive state of the checkbox. Usage: Managed automatically through user interaction. Context: Ensures clear feedback for pointer and keyboard users.

---

size (enum)

Options: base, sm, lg Purpose: Controls the overall dimensions of the checkbox. Usage:

• base → standard forms

• sm → compact layouts or dense UIs

• lg → high-visibility or touch-friendly contexts

Context: Should match surrounding typography and layout density.

---

is-selected (boolean)

Purpose: Controls whether the checkbox is checked. Usage:

• true → selected

• false → unselected

Context: Must remain in sync with application or form state.

---

is-disabled (boolean)

Purpose: Controls whether the checkbox is interactive. Usage:

• true → disables interaction and input

• false → fully interactive

Context: Applies muted styling and removes interactivity.

---

Appearance Modes:

Supports the following variable collections:

theme

• Adapts checkbox colors, borders, and icons for light and dark themes

• Maintains consistent contrast and visibility across all styles and states

• Error (alert) styling remains clearly distinguishable in all themes

style

• Semantic color and emphasis variations:

  • grey → neutral

  • cta → emphasized

  • alert → cautionary / critical

size

• Controls the physical dimensions of the checkbox and check icon

• Supported sizes:

  • sm → compact or dense layouts

  • base → standard form usage

  • lg → high-visibility or touch-friendly contexts

• Size scales consistently with surrounding typography and spacing tokens

status

• default: Resting state

• hover: Pointer feedback

• focus: Clear keyboard focus indicator

• active: Pressed interaction state

is-disabled

• false: Fully interactive with standard colors

• true: Reduced opacity and muted styling to indicate non-interactive state

ℹ️ The alert style may be combined with theme, size, and status modes, but remains semantically reserved for error states only.

---

Nested Components:

• Check Icon: Displays when is-selected = true, providing a clear visual indicator of selection.

---

♿ Accessibility Considerations:

• Contrast: Meets WCAG AA across all styles, sizes, and states.

• Keyboard navigation:

  • Reachable via Tab

  • Toggled with Space

  • Clear focus indicator in focus state

• Screen reader support:

  • Announces checked/unchecked state

  • Properly reads associated label text

  • Uses native checkbox semantics

• Semantic tags:

  • Implemented using semantic <input type="checkbox"> elements

  • Proper label association required

---

🧠 Developer Notes:

This component maps directly to a semantic <input type="checkbox">.

• State changes should propagate through form control logic

• is-selected must be controlled or synced in controlled components

• The check icon is a nested instance that animates between states

• Supports standard form validation and grouping patterns

---

Known Issues:

No known issues.

---

Reference Links:

• WCAG 2.1 – Checkbox & Form Control Accessibility

• ARIA Authoring Practices – Checkbox Pattern

• Dev Launchers Design Tokens (Color, Spacing, Radius)