Skip to content

EnInputBoolean ​

Preview ​

Props ​

NameDescriptionDefaultControl
value

Use v-model to bind to value of the input.

boolean | unknown[]
false
optionValue

Required when using multiple EnInputBooleans to return an array of values when not using a checkbox group.

any
null
inputLabel

Sets label next to checkbox.

string
""
inline

Sets 'checkbox-inline' style.

boolean
false
toggle

Sets the display to a more stylized toggle.

boolean
false
toggleSuccess

Sets the toggle style to the semantic success style.

boolean
false
toggleSize

Sets the size of the toggle.

string
"md"
trueText

Display text for inside the toggle, true side.

string
"Yes"
falseText

Display text for inside the toggle, false side.

string
"No"
deselectable

Lets the answer be taken back. Adds a clear button after the control that returns the value to null, and gives the toggle a third, unanswered state in which neither side reads as selected — so "not answered yet" is distinct from an answer of "No". Without it the field is two-valued as before.

boolean
false
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 name prop. This should always be matched to a label's "for" attribute for proper accessibility.

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 critical-field highlight, the element that carries has-error also carries is-critical, and a surrounding EnFormGroup adds a warning icon beside its label. Both clear once the field holds a value and return if it is cleared again: the yellow means "this important field is empty right now". A real error still wins.

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 EnFormGroup.

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' v-tooltip directive, which the consuming app registers.

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 displayOnly field shows in place of an empty value. Off by default, so an empty field renders nothing. true shows an em dash; a string shows that text instead. The placeholder is drawn in gray-700 so it reads as "nothing here" rather than as a value. EnForm and EnFormGroup take the same prop and hand it to every field they display.

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 fields prop of the EnForm component. Can be passed a function that returns true or false for conditional validation.

boolean | Function
true
renderInTable

Prevents a field from generating a column/heading in the EnTableBasic component. Can be passed a function that returns true or false for conditional validation.

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 ​

blur

No description

change

No description

input

No description

Methods ​

NameDescription
focus

Focuses the control. A deselectable field is a pair of radios rather than a single checkbox, so it focuses the first side.

Guidelines ​

Toggle or plain checkbox? ​

EnInputBoolean renders a plain checkbox by default, and a stylized toggle with the toggle prop. Functionally they're the same control — the choice is about prominence and density.

  • Lean toward the toggle. It's the more current treatment and carries more visual weight, which suits a control meant to be noticed: a filter above a list, a setting in a panel heading, a few options in a form.
  • Use the plain checkbox once there are many together — more than about four in a group. A permissions list, a per-row column in a table, or a dense settings form reads better with the compact, quieter control; a stack of toggles competes with the content it acts on.

Consistency is scoped to the group, not the page. Booleans that sit together — on one row, in one fieldset — should share a treatment; a toggle above a list and checkboxes inside the table below it is perfectly fine. So when a new toggle lands beside an older raw <input type="checkbox">, convert the neighbor rather than downgrading the new control to match it.

Starting convention

This records current practice so there's something to apply, rather than a rule Design has ratified. Pending sign-off — see front-end/beacon#17.

A parent checkbox over several children ​

A select-all or parent checkbox — one control that checks and clears a set of child checkboxes indented beneath it — is a composition, not a prop; EnInputBoolean has no indeterminate state of its own. When the children are table rows, use EnTableBasic's bulk actions: its select-all shows the indeterminate (partly checked) mark when only some rows are selected. That is the rule everywhere: a parent with some children checked reads as partly checked, never as unchecked. For standalone checkboxes a checkbox tree component is in progress (ui-components#132); until it ships, compose the parent and its indented children from EnInputBoolean and follow the table's partly-checked behavior.

When "not answered" is a real state ​

By default the field is two-valued: it holds true or false, and an unanswered field is indistinguishable from an answer of No. deselectable adds a third state. The control becomes a pill group of two options in which neither side reads as selected until the user picks one, plus a clear button that returns the value to null.

Use it wherever "No" and "hasn't said yet" mean different things — a compliance question that must be answered deliberately, a setting whose default should not be inferred, a filter that is off rather than negative.

A sliding toggle can't express this: it keys its styling off :checked, so a null value there looks exactly like No. That's why deselectable renders as a pill of two radios instead of a checkbox or toggle.

In displayOnly mode an unanswered deselectable field shows nothing, rather than resolving to falseText and reporting a "No" the user never gave. Set emptyValue to show a placeholder there instead (see empty values); a boolean without deselectable can't be empty, so it still reads null as No.

trueText and falseText ​

These aren't labels for the control — the field label carries the meaning. They are the text rendered inside the toggle, and the read-only value in displayOnly mode ("Yes" / "No" by default). Set them when the value needs domain wording rather than yes/no — e.g. trueText="Active" falseText="Inactive". The sm and xs sizes are fixed narrow pills with no room for text, so they matter most at the default md size and in displayOnly.

Examples ​

Alternate toggle styles controlled by prop ​

Tooltip slot ​