Validation message
<forma-validation-message>
Question- or field-level recovery guidance with a mark, bold text and no reliance on color.
- Authoring tag
<forma-validation-message>- Category
- Feedback and status
- Behavior owner
- Application state
- Canonical source
patterns/validation-message.html
Purpose
A validation message tells the user what is wrong with one answer and how to fix it, directly under the control or question it concerns. Forma renders a paragraph with a circled mark and emphasized text. The application decides whether a value is invalid, writes the message, links it to the control with aria-describedby, and sets aria-invalid on the control. Forma does not validate anything.
Use when
- A single field or question has a value that cannot be accepted, and the user can fix it in place.
- A required answer is missing after the user tried to continue.
- Each error in a longer form needs its own local explanation in addition to a Validation summary.
Avoid when
- Several fields failed at once: add a Validation summary at the top of the form and keep one message per field.
- The problem is with the page or the operation, not a field: use Alert or Operation status.
- The text is permanent help that is always shown: use the field description in Text field or the question help in Question shell.
Behavior to know
- The mark is a bordered circle in
currentColor, so the message is recognizable in grayscale and forced colors. - The text is bold and uses the primary text color; it does not turn the message red.
- It is a plain paragraph with no live-region role, so it is announced through the control's description rather than on insertion.
Basic example
The smallest correct markup: the canonical pattern from patterns/validation-message.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal validation message
Rendered from the canonical pattern file.
<forma-validation-message class="forma-component-tag">
<p class="forma-validation-message" id="question-example-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Choose one response before continuing.
</p>
</forma-validation-message>
Click or tap the code once to select all of it, then copy.
Examples
Email format error
A text field whose value was rejected. The input carries aria-invalid="true" and lists both the help text and the message in aria-describedby, so screen readers read the recovery guidance when the field is focused.
<forma-validation-message class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="validation-message-email-format-input">Billing contact email</label>
<span class="forma-field__description" id="validation-message-email-format-help">Invoices are sent to this address.</span>
<input id="validation-message-email-format-input" name="billing-email" type="email" autocomplete="email" value="accounts@example" aria-invalid="true" aria-describedby="validation-message-email-format-help validation-message-email-format-error">
<p class="forma-validation-message" id="validation-message-email-format-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter a full email address, such as accounts@example.com.
</p>
</div>
</forma-validation-message>
Click or tap the code once to select all of it, then copy.
Required choice not answered
A radio group left unanswered. The message follows the fieldset and is referenced from the fieldset with aria-describedby, so it is announced when focus enters the group.
<forma-validation-message class="forma-component-tag">
<fieldset class="forma-choice-group" aria-describedby="validation-message-required-choice-error">
<legend class="forma-choice-group__legend">Where is customer data stored?</legend>
<label class="forma-choice">
<input type="radio" name="validation-message-required-choice-storage" value="region" required>
<span class="forma-choice__content"><strong>In one region</strong></span>
</label>
<label class="forma-choice">
<input type="radio" name="validation-message-required-choice-storage" value="multi-region">
<span class="forma-choice__content"><strong>Across several regions</strong></span>
</label>
</fieldset>
<p class="forma-validation-message" id="validation-message-required-choice-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Choose where customer data is stored before continuing.
</p>
</forma-validation-message>
Click or tap the code once to select all of it, then copy.
Out-of-range number
A numeric value outside the allowed range. The message states the limits and the current value, so the user does not have to guess the rule.
<forma-validation-message class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="validation-message-range-guidance-input">Retention period (days)</label>
<input id="validation-message-range-guidance-input" name="retention-days" type="number" inputmode="numeric" value="4000" min="30" max="3650" aria-invalid="true" aria-describedby="validation-message-range-guidance-error">
<p class="forma-validation-message" id="validation-message-range-guidance-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter a value from 30 to 3,650 days. 4,000 is above the maximum.
</p>
</div>
</forma-validation-message>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile long message
A longer recovery message under a password field at phone width. The mark stays at the top of the first line while the text wraps beside it.
What changes at narrow widths
- The message is a flex row: the 1.5rem mark keeps its size and the text wraps in the remaining width.
- The mark aligns to the first line, so multi-line messages still read as one item.
- The message never widens the field or causes horizontal scrolling at 320px.
- Orientation changes only reflow the text; the message stays directly under its control.
<forma-validation-message class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="validation-message-mobile-long-input">New passphrase</label>
<input id="validation-message-mobile-long-input" name="new-passphrase" type="password" autocomplete="new-password" aria-invalid="true" aria-describedby="validation-message-mobile-long-error">
<p class="forma-validation-message" id="validation-message-mobile-long-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Use at least 12 characters. This passphrase also appears in a list of commonly used passwords, so choose something less predictable.
</p>
</div>
</forma-validation-message>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
id | p.forma-validation-message | unique id | — | Required so the control can reference the message. |
aria-describedby | input, select, textarea or fieldset | id list including the message id | — | Associates the message with the control so it is read when the control is focused. Keep any existing help text id in the list. |
aria-invalid | input, select or textarea | true | absent | Set by the application while the value is invalid; remove it when the value is fixed. |
aria-hidden | .forma-validation-message__mark | true | — | Hides the decorative glyph from assistive technology. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-validation-message | Block class | — | Paragraph root: a flex row of mark and text with bold, small primary-colored text. |
.forma-validation-message__mark | Element class | — | Bordered circular mark holding a short glyph such as !. Decorative. |
.forma-validation-message--when-invalid | Modifier class | — | Optional native-validation modifier: hidden until a sibling control reaches :user-invalid after an attempted submission. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | The message is not focusable. It is read as the description of the control it is linked to when that control receives focus. |
| Event | Description |
|---|---|
invalid / input / change | Native events on the associated control that the application may use to decide when to show or clear the message. Forma defines no events. |
Form behavior
The message does not participate in the form. Native constraint validation on the control (required, min, max, type) still runs unless the form has novalidate.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Shown | present in the DOM and referenced by aria-describedby | Visible under the control and announced as part of its description. |
| Cleared | removed from the DOM or from aria-describedby, and aria-invalid removed | The application removes the message once the value is acceptable. |
Accessibility
Forma provides
- Pairs a bordered mark with bold text, so the error does not depend on color.
- Keeps the mark decorative and the text as real content that assistive technology can read.
Your application supplies
- Reference the message from the control with
aria-describedbyand setaria-invalid="true"while the error applies. - Write guidance that says how to fix the value, not only that it is wrong; never show raw exception text.
- When several fields fail on submit, also render a Validation summary and move focus to it.
- Avoid showing messages while the user is still typing a first value.
Responsive behavior
- The flex row lets the text wrap to any width while the mark keeps its 1.5rem size.
- There are no breakpoints; the message follows the width of its field or question.
- Long words and numbers wrap with the surrounding text.
Motion
- No animation: the message appears and disappears with the application's DOM change. There is no entry cue, so the error is readable immediately.
Usage guidance
Do
- Place the message directly after the control or group it describes.
- Keep it to one or two sentences and name the expected format or range.
Avoid
- Relying on a red border or color change to show an error.
- Adding
role="alert"to each field message; announce the set once through a Validation summary.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.