Checkbox
The e-checkbox component captures boolean or mapped on/off values with a field-consistent contract, including validation, helper details, and disabled/readonly states.
Use this page to validate interaction patterns, model mapping, and accessibility-friendly labeling before integrating checkbox flows into production forms.
Usage
Use this baseline playground to configure checkbox behavior in context: color, outlined, disabled, readonly, tonal, and retain-color for stronger state continuity.
Visual variants
Compare default, outlined, tonal, retain-color, active, disabled, and readonly states to keep semantic intent clear in dense forms.
Custom values
Map checkbox state to domain values with true-value and false-value when your form contract is not strictly boolean.
Named slots
Use the label slot to render richer labels with links or helper context while keeping native checkbox semantics.
Validation
Validate consent-style flows with required rules and explicit submit-state feedback before continuing critical actions.
Submit to validate the checkbox rule.
Props
Use the API table as the source of truth for accepted types, defaults, and inherited field behavior.
| Property | Type | Default |
|---|---|---|
| modelValue | boolean | string | number | undefined |
Current checkbox value. Checked state is resolved by strict equality against trueValue. | ||
| trueValue | boolean | string | number | true |
Value emitted when the checkbox becomes checked. | ||
| falseValue | boolean | string | number | false |
Value emitted when the checkbox becomes unchecked. | ||
| tonal | boolean | false |
Shows field overlay styling inside the control slot without changing behavior. | ||
| clearable | boolean | false |
Shows clear action when a value exists. | ||
| color | string | "primary" |
Base theme color applied to field state and interactions. | ||
| outlined | boolean | false |
Uses outlined visual variant for the field container. | ||
| disabled | boolean | false |
Disables interaction and prevents value updates. | ||
| readonly | boolean | false |
Prevents editing while preserving focus behavior. | ||
| dense | boolean | false |
Applies denser vertical spacing inherited from Field. | ||
| retainColor | boolean | false |
Keeps active color styling after focus/interaction. | ||
| label | string | number | undefined |
Field label text. | ||
| labelMinWidth | string | number | undefined |
Minimum width reserved for label region. | ||
| labelBehavior | "static" | "static" |
Label behavior is static for checkbox controls. | ||
| inputAlign | left | right | center | start | end | "start" |
Horizontal text alignment inside input/selection area. | ||
| prependIcon | string | IconPath | IconPath[] | undefined |
Icon rendered in outer-left affix region. | ||
| prependInnerIcon | string | IconPath | IconPath[] | undefined |
Icon rendered before content inside input frame. | ||
| appendInnerIcon | string | IconPath | IconPath[] | undefined |
Icon rendered after content inside input frame. | ||
| appendIcon | string | IconPath | IconPath[] | undefined |
Icon rendered in outer-right affix region. | ||
| detail | string | undefined |
Helper text shown in details area when no errors are present. | ||
| detailsOnMessageOnly | boolean | false |
Shows details area only when messages/errors exist. | ||
| rules | FieldRule | undefined |
Validation rules evaluated against modelValue. | ||
| detailErrors | string[] | undefined |
Explicit error messages rendered in details area. | ||