EnInputCheckbox
A single checkbox. This is the low-level building block that EnInputBoolean and EnInputCheckboxGroup render internally.
Reach for the higher-level components first
- For a single yes/no choice (agree to terms, enable a setting), use EnInputBoolean — it wraps
EnInputCheckboxand adds the label, validation, error display, and toggle styles. - For a set of related choices, use EnInputCheckboxGroup with an
optionsarray — it provides the group label, array model handling, validation and error display, and grouping accessibility semantics.
Only use EnInputCheckbox directly when you need a custom layout the higher-level components can't render — for example, checkboxes inside a table, custom markup between options, or an option with its own embedded input.
Using checkboxes in a set
When composing a set out of individual EnInputCheckbox components, every checkbox in the set must:
- Bind to the same array
v-model— each checked box adds itsoptionValueto the shared array. - Share the same
nameso the set submits and reads as one field. - Have a distinct
optionValueand a distinctid(theiddefaults toname, which collides across a set, so set it explicitly).
Unlike the group component, standalone checkboxes render no group label and no validation errors. Wrap the set in a labelled container (e.g., role="group" with aria-labelledby, or <fieldset>/<legend>) and handle error display yourself — or use EnInputCheckboxGroup, which does all of this for you.
Playground
Preview
Props
| Name | Description | Default | Control |
|---|---|---|---|
| optionValue | any | null | |
| inline | boolean | false | |
| single | boolean | false | |
| toggle | boolean | false | |
| toggleSuccess | boolean | false | |
| toggleSize | string | "md" | |
| trueText | string | "" | |
| falseText | string | "" | |
| nullable | Lets the control show a third, unanswered state: while the value is null
neither side of the toggle reads as selected. Set by EnInputBoolean's
boolean | false | |
| handlers | Record<string, any> | unknown | |
| lockedTooltip | The Record<string, any> | null | |
| styled | boolean | false | |
| value | Used for a raw value passed into the input. string | number | unknown | |
| name | Sets name attribute for the input. Required for proper form handling. string | null | |
| id | Sets id attribute for input. If left blank, it will default to the string | null | |
| placeholder | Sets the placeholder value. string | null | |
| label | Used to describe field in error message string | null | |
| disabled | Sets the disabled attribute. boolean | null | |
| required | Sets the field to required. boolean | false | |
| critical | Flags the field as critical. Critical is not required: a required field blocks saving, while a critical field saves fine empty but blocks something later, such as activating or completing a record. Use it for "you will need this before you can finish", not "you must enter this now". While the field is empty, the control takes the boolean | false | |
| locked | Locks the field: disables the control and marks it with a lock icon. Text-like controls show the
lock inside the input, in the spot a select keeps its arrow. Option groups, booleans and file
inputs have no box to put it in, so they show it beside the label of a surrounding boolean | false | |
| lockedMessage | Why the field is locked, for example "Locked while payroll is open". Shown as a tooltip when the
pointer rests on the locked control, and on the lock icon beside the label, which becomes
focusable so keyboard users can reach the text (the disabled control itself cannot take focus).
Rendered through en-components' string | "" | |
| typeCast | Used to specifically validate different types. string | "string" | |
| mode | Sets when and how often validation occurs. TODO: create docs for modes string | "eager" | |
| displayOnly | Displays the value of the field in a span element, instead of as an input. boolean | false | |
| emptyValue | What a string | boolean | false | |
| rules | A pipe separated string of validation rules for the field. View validation rules string | "" | |
| renderInForm | Prevents a field from being rendered at all when used in the boolean | Function | true | |
| renderInTable | Prevents a field from generating a column/heading in the boolean | Function | true | |
| customMessages | Provide a custom error messages by rule. Should be an object with keys that match the rule name and value being a string of the message to display. Record<string, any> | null |
Slots
tooltip
No description
Events
No events defined.
Methods
| Name | Description |
|---|---|
| focus | Focuses the checkbox input element. |
Related Components
- EnInputBoolean — Preferred for a single true/false choice; also provides toggle styles.
- EnInputCheckboxGroup — Preferred for standard option sets; adds label, validation, errors, and layout.
- EnInputRadio — For mutually exclusive choices.