Validation Overview — Form Validation

When Validation Runs

Validation has three trigger points:

Trigger	When It Fires	Controlled By
On change	Every time a field value changes	`autoValidate: true` on `FormRenderer`
On blur	When focus leaves a field	Default behaviour for most controls
On submit	Before the form submit action executes	Always runs — cannot be bypassed

autoValidate Mode

Pass autoValidate={true} to FormRenderer to enable real-time per-keystroke validation. This is ideal for forms that need immediate feedback (e.g., registration forms with username availability checks):

import { FormRenderer } from '@atlas-forms/player-components-react';

<FormRenderer
  schema={schema}
  initialValues={initialValues}
  autoValidate={true}
  onSubmit={handleSubmit}
/>

Validation Object in Schema

Each control can have a validation object in its schema definition. All properties are optional — include only the rules you need:

{
  "id": "company-name",
  "type": "text",
  "label": "Company Name",
  "validation": {
    "required": true,
    "minLength": 2,
    "maxLength": 100,
    "pattern": "^[A-Za-z0-9 \\-\\.]+$",
    "patternMessage": "Only letters, numbers, spaces, hyphens and dots allowed"
  }
}

Validation Architecture

The validation pipeline processes rules in this order on each field:

Required check — short-circuits if the field is empty and required
Type coercion check — ensures the value matches the expected type
Built-in rule evaluation — minLength, maxLength, min, max, pattern, email, url
Custom synchronous validators — registered via registerValidator()
Custom asynchronous validators — debounced, run after synchronous rules pass
Cross-field validators — run after individual field validation

ValidationResult Type

// packages/types-js/src/validation.types.ts
interface ValidationResult {
  valid: boolean;
  message?: string;    // Error message to display
  field?: string;      // Field ID — used for cross-field errors
}

// Validator function signature
type ValidatorFn = (
  value: any,
  fieldId: string,
  allValues: Record<string, any>
) => ValidationResult | Promise<ValidationResult>;

Form-Level vs Field-Level Validation

Level	Where Defined	Use For
Field-level	`control.validation` object	Rules that apply to a single field's value
Cross-field	Custom validator with access to `allValues`	Rules that compare two fields (e.g., confirm password, date range)
Form-level	`formValidators` array on the schema root	Business rules that span multiple fields (e.g., at least one contact method required)

Next: Built-In Rules →