Error Display
Validation errors appear inline below the failing field by default. Atlas Forms also supports an optional error summary panel that lists all errors at the top of the form, accessible keyboard navigation between errors, and ARIA live region announcements for screen reader compatibility.
Inline Error Messages
Each control renders its own error message directly below the input when validation fails. The error text uses the red colour from the theme's error palette and includes an icon. This is automatic — no additional configuration is needed:
// The validation message defined in schema is shown inline automatically
{
"id": "email",
"type": "email",
"label": "Email Address",
"validation": {
"required": true,
"requiredMessage": "Email address is required to send your receipt",
"email": true,
"emailMessage": "Enter a valid email address (e.g. name@company.com)"
}
}Error Summary Panel
Enable an error summary panel by adding an error-summary control to the form schema. Place it near the top of the form so it's visible after a failed submit attempt. The summary auto-populates with all current errors and includes links that scroll to each failing field:
{
"id": "validation-summary",
"type": "error-summary",
"width": "full",
"settings": {
"title": "Please correct the following errors before submitting:",
"showOnSubmitOnly": true, // Only show after a submit attempt
"scrollToFirst": true // Auto-scroll to first error on submit
}
}error-summary Settings
| Setting | Type | Default | Description |
|---|---|---|---|
title | string | "Please correct the following errors:" | Heading shown above the error list |
showOnSubmitOnly | boolean | false | Hide summary until a submit has been attempted |
scrollToFirst | boolean | true | After a failed submit, automatically scroll the page to the first error |
includeFieldLabels | boolean | true | Prefix each error with the field label: "Email Address: Enter a valid email address" |
Async Validation Indicators
While an async validator (e.g., a server-side availability check) is running, the control shows a loading spinner in place of the error message. Once the async result returns, it switches to the error message or clears. This is automatic — no configuration needed.
ARIA Accessibility
The validation system follows WCAG 2.1 AA guidelines:
| Element | ARIA Attribute | Value |
|---|---|---|
| Invalid input | aria-invalid | "true" |
| Error message container | role | "alert" |
| Error message | aria-live | "polite" — announced by screen readers without interrupting |
| Input ↔ error link | aria-describedby | Points to the error element ID |
| Error summary | role | "alert" with aria-live="assertive" on submit |
Controlling Error Visibility Timing
By default, errors appear on blur (when the field loses focus). You can control this through the FormRenderer props:
// Show errors immediately on every change (aggressive — good for high-stakes forms)
<FormRenderer autoValidate={true} validateOn="change" ... />
// Show errors only after blur (default — less disruptive)
<FormRenderer validateOn="blur" ... />
// Show errors only when the user attempts to submit
<FormRenderer validateOn="submit" ... />Custom Error Styling
The error message element has a fixed CSS class (.af-field-error) that you can target in your shared CSS or theme to customise appearance:
/* In your custom theme or shared.css */
.af-field-error {
color: #dc2626;
font-size: 0.75rem;
margin-top: 4px;
display: flex;
align-items: center;
gap: 4px;
}
/* Error state on the input itself */
.af-control-invalid input,
.af-control-invalid textarea {
border-color: #dc2626;
box-shadow: 0 0 0 2px rgba(220, 38, 38, 0.15);
}