Checkbox

Usage

• Use Checkbox for independent binary choices where zero or more options can be selected.
• Use Radio instead when only one choice is allowed in a group.
• Use Toggle instead when the setting takes effect immediately without form submission.
• Use a standalone Checkbox for single choices like confirming an action, agreeing to terms, or enabling a feature.
• Use CheckboxGroup for multiple related options to enable parent controls and a shared label.

Behaviors

• Disabled state (isDisabled) prevents interaction and applies a dimmed visual treatment.
• Danger state (isInvalid) applies critical color treatment. Pair with the error prop to display a message below the Checkbox.
• Indeterminate state (isIndeterminate) replaces the checkmark with a horizontal dash to communicate partial group selection.
• Use indeterminate on a parent Checkbox when only some children in a group are selected. Never show the parent as checked when only some children are selected.
• Indeterminate is purely visual and is independent of the checked state.
• Truncation (shouldTruncateLabel) clips the label with an ellipsis to prevent wrapping when labels may exceed the parent container width.

Content

• Write labels that clearly describe what option the Checkbox controls. Labels must be self-explanatory without surrounding context.
• For option Checkboxes, phrase labels as the setting or feature being enabled (e.g., "Send weekly digest").
• For confirmation or agreement Checkboxes, use short first-person statements (e.g., "I agree to the terms of service").
• Use the description prop to add context beyond the label. Keep descriptions as short phrases without end punctuation.
• Never restate the label in the description.
• Frame error messages (error) as direct instructions with guidance on how to fix the issue. Never use "Please".

Implementation Notes

• Provide label for visible label text. If no visible label is used, provide ariaLabel or ariaLabelledby for accessibility.
• In React, label accepts ReactNode for rich content. In Ember, use the :label named block for rich label content, or the @label arg for plain text.
• Use onCheckedChange for state changes. onChange is deprecated.
• onCheckedChange receives (checked: boolean, event).
• When inside a CheckboxGroup, isChecked and name are managed by the group context and do not need to be set on individual Checkboxes.
• Ember invocation: <PlumaCheckbox @isChecked={{...}} @onCheckedChange={{...}} @label="..." />.