Validation

Every field in @saastro/forms needs validation. There are three ways to set it up, from simplest to most flexible:

Most developers only need the first two. The rest are there when you need them.

FieldBuilder Methods

The recommended approach. Chain validation methods on any field:

import { FormBuilder } from '@saastro/forms';

const config = FormBuilder.create('signup')
  .addField('name', (f) =>
    f.type('text').label('Name').required().minLength(2, 'Name is too short'),
  )
  .addField('email', (f) =>
    f.type('email').label('Email').required().email('Please enter a valid email'),
  )
  .addField('password', (f) =>
    f
      .type('text')
      .label('Password')
      .required()
      .minLength(8)
      .regex('^(?=.*[A-Z])(?=.*\\d)', 'Must have 1 uppercase and 1 number'),
  )
  .addField('terms', (f) =>
    f.type('checkbox').label('I accept the terms').mustBeTrue('You must accept the terms'),
  )
  .addStep('main', ['name', 'email', 'password', 'terms'])
  .build();

All Methods

Every method accepts an optional custom error message. Without one, a sensible default is used.

Presets

For common validation patterns, use a single preset instead of multiple rules:

.addField('phone', (f) =>
  f.type('tel').label('Phone').preset('phone-us')
)

.addField('password', (f) =>
  f.type('text').label('Password').preset('password-strong')
)

Built-in Presets (19)

Identity & Auth:

Contact:

Technical:

Custom Presets

Register your own:

import { registerPreset, getAvailablePresets } from '@saastro/forms';

registerPreset({
  id: 'company-email',
  label: 'Company Email',
  description: 'Must be a @company.com email',
  category: 'string',
  rules: {
    format: 'email',
    pattern: '@company\\.com$',
    patternMessage: 'Must be a @company.com address',
  },
});

// Now use it like any built-in preset
.addField('email', (f) => f.type('email').label('Work Email').preset('company-email'))

Advanced: ValidationRules Object

Under the hood, FieldBuilder methods produce a ValidationRules object — a flat, JSON-serializable structure. You can write this object directly when your form configs come from a database, API, or visual builder.

// These two are equivalent:
.addField('email', (f) => f.type('email').label('Email').required().email())

.addField('email', (f) => f.type('email').label('Email').schema({
  required: true,
  format: 'email',
}))

This is what makes @saastro/forms work with the visual Form Builder — the entire validation config is JSON-storable.

All Properties

Escape Hatch: Raw Zod Schemas

When you need validation logic that can’t be expressed as simple rules — async checks, cross-field validation, transforms, or Zod pipes — pass a Zod schema directly:

import { z } from 'zod';

.addField('email', (f) =>
  f.type('email')
    .label('Email')
    .schema(z.string().email().endsWith('@company.com', 'Must be a company email'))
)

.addField('age', (f) =>
  f.type('text')
    .label('Age')
    .schema(z.coerce.number().min(18, 'Must be 18 or older').max(120))
)

Note: Once you use .schema(zodSchema), the FieldBuilder validation methods (.required(), .email(), etc.) have no effect — the Zod schema takes full control. Don’t mix them.

Custom Validators (via Plugins)

For async or server-side validation (like checking if an email is already taken), use plugin validators:

import { definePlugin, PluginManager, FormBuilder } from '@saastro/forms';

const myPlugin = definePlugin({
  name: 'my-validators',
  version: '1.0.0',
  validators: {
    uniqueEmail: async (value, context) => {
      const res = await fetch(`/api/check-email?email=${value}`);
      const { exists } = await res.json();
      return exists ? 'Email already registered' : true;
    },
  },
});

const pm = new PluginManager();
pm.register(myPlugin);

const config = FormBuilder.create('signup')
  .usePlugins(pm)
  .addField(
    'email',
    (f) => f.type('email').label('Email').required().email().customValidators('uniqueEmail'), // Runs after the built-in checks pass
  )
  .addStep('main', ['email'])
  .build();

Validators return true for valid or an error message string for invalid. See Plugins for full details.

How It Works Internally

When a field uses ValidationRules (not a raw Zod schema), the compiler picks a base Zod type from the field type, then layers on your rules:

The compilation order is: resolve preset → merge explicit rules → apply type-specific constraints → handle required: false with .optional().

API Reference

import type { ValidationRules, SchemaType } from '@saastro/forms';
import {
  compileValidationRules, // (rules, fieldType) => ZodSchema
  isZodSchema, // type guard for Zod schemas
  isValidationRules, // type guard for ValidationRules objects
  resolvePreset, // (id) => ValidationRules | undefined
  registerPreset, // register a custom preset
  getAvailablePresets, // list all presets (built-in + custom)
} from '@saastro/forms';