Feedback and status

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

Canonical

Minimal validation message

Rendered from the canonical pattern file.

Choose one response before continuing.

HTML · Minimal validation message Raw HTML for HTML · Minimal validation message
<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

Scenario

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.

Invoices are sent to this address.

Enter a full email address, such as accounts@example.com.

HTML · Email format error Raw HTML for HTML · Email format error
<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.

Scenario

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.

Where is customer data stored?

Choose where customer data is stored before continuing.

HTML · Required choice not answered Raw HTML for HTML · Required choice not answered
<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.

Scenario

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.

Enter a value from 30 to 3,650 days. 4,000 is above the maximum.

HTML · Out-of-range number Raw HTML for HTML · Out-of-range number
<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 example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile long message Raw HTML for HTML · Mobile long message
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
idp.forma-validation-messageunique id—Required so the control can reference the message.
aria-describedbyinput, select, textarea or fieldsetid 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-invalidinput, select or textareatrueabsentSet by the application while the value is invalid; remove it when the value is fixed.
aria-hidden.forma-validation-message__marktrue—Hides the decorative glyph from assistive technology.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-validation-messageBlock class—Paragraph root: a flex row of mark and text with bold, small primary-colored text.
.forma-validation-message__markElement class—Bordered circular mark holding a short glyph such as !. Decorative.
.forma-validation-message--when-invalidModifier class—Optional native-validation modifier: hidden until a sibling control reaches :user-invalid after an attempted submission.
Keyboard interaction
KeysResult
Tab / Shift+TabThe message is not focusable. It is read as the description of the control it is linked to when that control receives focus.
Events
EventDescription
invalid / input / changeNative 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

Validation message states
StateHow it is expressedPresentation
Shownpresent in the DOM and referenced by aria-describedbyVisible under the control and announced as part of its description.
Clearedremoved from the DOM or from aria-describedby, and aria-invalid removedThe 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-describedby and set aria-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.