Checkbox

Checkboxes are used for multiple selection in a list, or for a single binary choice (like "Remember me" or "Accept terms"). The MD3 Expressive Checkbox features fluid motion when transitioning between checked, unchecked, and indeterminate states.

Introduction

The MD3 Expressive Checkbox is designed for high tactile feedback. It uses SVG path morphing to animate the transition from empty to checked or indeterminate. This motion is not just decorative; it provides a clear confirmation of the user's action.

Anatomy

• Container: The outer box that holds the checkmark.
• Checkmark / Dash: The visual indicator of the state (checked or indeterminate).
• Label (Optional): Descriptive text linked to the checkbox.
• State Layer: Shows hover and pressed states with a ripple effect.

Variants

Basic Checkbox

The standard binary choice.

Labeled Checkbox

Use the label prop to automatically create an accessible, clickable label.

Tri-State Checkbox

A specialized component that cycles through three states: unchecked → checked → indeterminate.

Features

Indeterminate State

Used when a parent checkbox represents a collection of items where only some are selected.

States

Checkboxes support error, disabled, and readOnly states.

Usage

Basic Usage

import { Checkbox } from "@bug-on/m3-expressive";

<Checkbox label="Accept Terms & Conditions" />

Controlled Tri-State

import { TriStateCheckbox } from "@bug-on/m3-expressive";

const [state, setState] = useState("unchecked");

<TriStateCheckbox 
  state={state} 
  onStateChange={setState} 
  label="Select All" 
/>

Best Practices

Do

• Use checkboxes for multiple selection in a list.
• Use a single checkbox for a binary choice (on/off) where the effect is not immediate (use a Switch for immediate effects).
• Group related checkboxes together.
• Use labels for all checkboxes to ensure accessibility and ease of use.

Don't

• Don't use a checkbox for an action that has an immediate effect (e.g., toggling dark mode); use a Switch instead.
• Avoid placing more than 10-12 checkboxes in a single group without sub-headers.

Accessibility

• Keyboard: Full support for Tab to focus and Space to toggle.
• ARIA: indeterminate state correctly sets aria-checked="mixed".
• Linking: Automatically links labels to inputs using id and htmlFor.
• Validation: Sets aria-invalid="true" in error state.

API Reference

Checkbox

TriStateCheckbox