Forms
Usage
- Caution when using
<button>inside of<form>elements with AJAX withouttype="button"as this will trigger the default form submission action - Radio and checkbox inputs should be inside their
<label>to ensure proper styling
Accessibility
- Every input should have a label with the
forattribute pointing to theidof the input, thereforidshould always be unique - If having a label doesn't make sense, using the
aria-labelattribute on the input is a good alternative
Inputs
Selects
Checkboxes
Radios
Layout
Vertical layout is preferred and should be the standard, however there are times when horizontal may make more sense.
Inline form groups
form-group-inline lays a single form-group out as one row — label in a fixed-width first column, control sized to its content in the second. It is for settings lists where every row is one question: "Spouses enrolled over restricted age can keep coverage [Yes|No]". The stacked label-above-control default still applies everywhere else.
Below the md breakpoint the row falls back to the stacked default, because a fixed label column plus a control doesn't fit a narrow panel.
Pair it with a label-width interval, and use the same interval on every row in one list or the controls won't line up. Pick the one that lets the longest label wrap at most once:
form-group-label-160 · -200 · -240 (the default width) · -280 · -320 · -360 · -400
Or size the label column as a share of the row, in twelfths. This is the one to reach for when moving a form off col-md-N / col-md-(12-N) columns, because it keeps that proportion. It resolves against the group's own width, so it holds in a modal and a full-width panel alike:
form-group-label-col-2 · -3 · -4 · -5 · -6
form-group-w-* caps the control without capping the label or the field error, so a select in a wide panel doesn't stretch the full column. On an inline group it also caps the control column at that width: without it each row's control is sized to its own content, so two rows with different options don't line up. The column gives way when the panel is too narrow for label and control together, rather than overflowing it. Use one interval across the list, the same way as the label width. Finer steps than the page-level max-width-* utilities:
form-group-w-100 · -150 · -200 · -250 · -300 · -400 · -500
form-group-w-fill instead lets the control fill whatever the label leaves. That suits a form rather than a settings list — a modal of text inputs and selects that should all end at the same right edge. It isn't the default because a list of toggles and short selects reads better with each control sized to its content. It does nothing on a stacked group.
The width classes inherit, so they can go once on a wrapper instead of on every row. A container with form-group-label-col-4 form-group-w-fill gives every form-group-inline inside it a one-third label column and a control that fills the rest:
The settings list below uses fixed intervals per row instead:
In the Vue form components, put the classes on EnFormGroup — the label-container it renders is the first column, and its tooltip prop puts the info trigger inside the label.
Help text
help-block is the message that belongs to one field. It renders as a muted block beneath the input and is scoped to that field the way an alert is scoped to a page, modal, or panel. Use it for anything the reader needs while working on that field — what the field means, how a particular option behaves, what format is expected — and equally for a state-specific notice: a temporary message that applies only while the field is in a particular state, such as a password field that will replace the saved value on save, or a record whose activation will deactivate another. A state-specific notice appears with the state and leaves with it; it is still help text, not an alert.
The first field below carries permanent guidance. The second shows a state-specific notice as it looks after “Change password” is clicked, until the save succeeds.
Contexts
Help text is neutral by default. When the message warns rather than informs, give it a context with a text color utility and a leading icon on the same line, so the meaning does not rest on color alone: help-block text-warning with icon-warning for a consequence the reader should weigh before acting, help-block text-info with icon-info for a notice worth noticing but not acting on. Keep the default muted treatment for ordinary guidance.
Two things beneath a field are not help text. Red text is reserved for a validation error — error-message means the value is invalid and blocks saving (see Validation), so a notice that is not an error never borrows it. And an alert never sits beneath a field: alerts are scoped to the page, modal, or panel, not to one input.
A styled contextual variant (a tinted background with a leading icon) and a help text prop on EnFormGroup are proposed in front-end/beacon#40.
Help text or a tooltip? Guidance needed every time the field is used belongs in help-block, where it's always visible. An EnTooltip or EnPopover trigger beside the label is for the optional case — a caveat, a piece of troubleshooting, something most people won't need. Keep to one trigger per field: two info icons on one label row are visually indistinguishable, so the reader has to open both to find out which is which. If a field seems to need two, one of them is usually help text.
In the Vue form components, use EnFormGroup's tooltip prop for the trigger. EnFormGroup has no help text prop yet, and its after slot sits on the field's line rather than beneath it, so render the help-block yourself directly after the group.
help-block is benefits-theme only — it isn't in the employee stylesheet.
Character counter
A field with a character limit shows how close the value is to it with a character counter: a line directly beneath the field reading “n / max”, right-aligned, in text-smaller text-muted, switching to text-danger once the count reaches the limit. It takes the help text position and size because it is guidance for the field, not an error. Navigator already uses this shape for the I-9 send-back note, the employee I-9 review form, and the HR escalation note in the employee AI chat.
Enforce the limit as well as showing it. Put maxlength on the input, which the Vue inputs forward to the native control, so typing stops at the cap, and add the maxvalidation rule so a pasted or prefilled value past the cap is reported as an error rather than silently truncated.
In the Vue form components the counter sits after EnFormGroup, not inside it: the group renders only its first slot child, so a sibling placed inside is dropped. Bind the count to the same model as the field.
vue
<EnFormGroup label="Reason for reset" required>
<EnInputTextarea name="reason" v-model="reason" rows="4" maxlength="500" rules="max:500" />
</EnFormGroup>
<p class="text-smaller text-right margin-top-8"
:class="reason.length >= 500 ? 'text-danger' : 'text-muted'">
{{ reason.length }} / 500
</p>Keep the counter beneath the field rather than on the label line. A count pulled right in label-inner sits where the reader is not looking while typing, and the one Navigator form that does this should migrate to the shape above.
The counter is visual only. None of the existing uses announce it to a screen reader, and whether it should be a live region is an open design question; in the meantime maxlength stops the typing for every user, and the max rule reports an over-long value as an error.
Validation
Use the error-message class to display the error under the input. There is also a has-error class that can be applied to the form-group to highlight the input.
Field states
Two states sit alongside has-error, and go on the same wrapper. The form components set them from their critical and locked props, and that is where the markup should come from; the classes are listed here so the stylesheet is accounted for.
is-criticalhighlights a field that can be left empty now but must be filled before something later can happen. The control's border and glow turn yellow; controls without aform-controlbox (a toggle track, a pill group, a button group, a file drop) take a solid ring instead. It steps aside forhas-error, so a real error still reads as one.critical-fieldon the control itself does the border highlight alone.is-lockeddraws a padlock inside the control, in the spot a select keeps its arrow, alongsidedisabledon the input. It is a background image, so it stays inside the box whatever addons flank it. Insideform-group-inlinethe extra right padding is dropped, so a locked control does not read as wider than its neighbors.form-label-indicatorsis the row of icons after a label's text, each one aform-label-indicator: the tooltip trigger,-criticalfor the warning,-lockfor controls with no box to draw the lock in. It is inline, so it trails the text in both the stacked and the horizontal layouts and leaves the required asterisk alone on the left.
Addons
Addons provides a way to add text or an icon to either side of the input field. In these examples, input-group-addon, input-group-btn, input-group-inner-addon classes are used to apply styles.
Input Group Buttons
Wrap a <button> in input-group-btn to attach an action to either side of an input. Bordered button styles (btn-secondary, btn-link) align flush with the input border, while filled buttons (btn-primary, btn-success) sit edge to edge.