FormState Guide

npm install react react-dom zod
npm install github:dstarosta/FormState#v1.0.0

import { useFormState, z } from 'form-state';

// eslint.config.js
import { defineConfig } from 'eslint/config';
import formStatePlugin from 'form-state/eslint';

export default defineConfig([
  {
    extends: [
      // ... your other configs
      formStatePlugin.configs.recommended,
    ],
    rules: {},
  },
]);

rules: {
  'form-state/avoid-input-password': 'error',
}

<input
  name="bio"
  defaultValue={formState.data.bio}
  onBlur={(e) => formActions.change('bio', e.target.value, { touch: true })}
/>

import { getState } from 'form-state';

const address1Zip = getState(formSchema, data, (path) => path.addresses[0].zipCode);

import { createState } from 'form-state';

const data = createState(schema);

// Override some default property values with a partial initial state object.
const data = createState(schema, { name: 'John', info: { age: 24 } });

import { updateState } from 'form-state';

const updatedTags = updateState(data.tags, (draft) => {
  draft.push('Important'); // can be a complex array/object structure
});

formActions.change('tags', updatedTags);

import { type FormPath } from 'form-state';

// A component that displays an error for any field
function FormError<T>({
  path,
  errors,
}: {
  path: FormPath<T>;
  errors: FormState<T>['errors'];
}) {
  const message = errors.get(path as (p: T) => unknown);
  return message ? <p className="error">{message}</p> : null;
}

// Caller — the compiler checks the path against FormSchema
<FormError path={(path: FormSchema) => path.info.age} errors={formState.errors} />

import { type FormState } from 'form-state';

// Debounce callback — typed state snapshot
function NoteTextInput({
  index,
  callback,
}: {
  index: number;
  callback?: (state: FormState<FormSchema>) => void;
}) {
  const { formActions } = useSchemaFormState();

  return (
    <input
      onChange={(e) =>
        formActions.change((path) => path.notes[index].text, e.target.value, {
          debounceIntervalMs: 500,
          callback,           // fires after debounce with latest FormState
          touch: true,
        })
      }
    />
  );
}

import { type FormMode } from 'form-state';

type ModeSelectorProps = {
  mode: FormMode;
  onChange: (mode: FormMode) => void;
};

// The compiler rejects anything that is not a valid mode string
formActions.setMode('readOnly');   // ✅
formActions.setMode('published');  // ❌ Type error

import { type SubmitState } from 'form-state';

const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) {
    // state.errors is Record<string, string>
    // state.data is DeepPartial<FormSchema> — may have empty/invalid fields
    return state.errors;
  }

  // state.data is fully typed FormSchema here — no cast needed
  await api.save(state.data.name);   // string, not string | ''
  await api.save(state.data.age);    // number, not number | ''
  return true;
};

import { type SubmitSuccessState } from 'form-state';

function App() {
  const handleFormSubmit = ({ data, formData }: SubmitSuccessState<FormSchema>) => {
    // data is fully typed FormSchema
    const output = formData.get('output');
    if (output === 'redirect') {
      router.push('/done');
    } else {
      showDialog({ data, formData });
    }
  };

  return <AppForm onSubmitted={handleFormSubmit} />;
}

import { type SchemaDataObject } from 'form-state';

// Component that displays clean API-ready data
function JsonData({ data }: { data: SchemaDataObject<FormSchema> }) {
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

// Usage
<JsonData data={schema.toObject(formState.data)} />

import { type StateChangeListener } from 'form-state';

// Define once outside the component to keep the reference stable
const listener: StateChangeListener<FormSchema> = ({ type, data, submitCount }) => {
  if (type === 'submit') {
    analytics.track('form_submit', { count: submitCount, name: data.name });
  }
};

// In your component:
formHooks.useListener(listener);

import { type DeepPartial } from 'form-state';

const { data: draft } = useQuery<DeepPartial<FormSchema>>({
  queryKey: ['draft', draftId],
  queryFn:  () => api.getDraft(draftId),
});

// Pass it directly as initialData — no need to fill in every field
const { formState, formActions } = useFormState(schema, {
  initialData: draft,
});

MIT License

Copyright (c) 2026 Dmitry Starosta

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

import { z } from 'form-state';

const schema = z.strictObject({
  // Required string with custom error and extra validators
  name: z
    .formString(
      { required: true, error: 'Name is required' },
      z.regex(/^[\w\s'-]+$/, 'Name contains invalid characters'),
      z.maxLength(50, 'Name must be 50 characters or less')
    )
    .with(z.describe('Full Name')),

  // Optional number with range constraints
  age: z
    .formNumber(z.gte(0, 'Age must be positive'), z.lte(150, 'Age is out of range'))
    .with(z.describe('Age')),

  // Date with a specific display format
  birthDate: z
    .formDate(
      { dateFormat: 'MM/dd/yyyy' },
      z.gte(new Date(1900, 0, 1), 'Date too far in the past')
    )
    .with(z.describe('Birth Date')),

  // Enum — only these string literals are valid
  status: z.formValues(['active', 'inactive', 'pending']).with(z.describe('Status')),

  // Boolean without an empty string value
  isAdmin: z.formBoolean({ required: true }).with(z.describe('Admin')),

  // Array of strings with length limits
  tags: z.formArray(z.string(), { minLength: 0, maxLength: 10 }).with(z.describe('Tags')),
});

type Schema = z.infer<typeof schema>;
// {
//   name: string;
//   age: number | '';
//   birthDate: Date | '';
//   status: 'active' | 'inactive' | 'pending' | '';
//   isAdmin: boolean;
//   tags: string[];
// }

const schema = z
  .strictObject({
    priority: z.formBoolean(),
    notes: z.formArray(
      z.object({ typeId: z.formNumber(), text: z.formString() })
    ),
  })
  .check(
    z.validate(
      (data) => data.priority || data.notes.every((note) => note.typeId !== 2),
      { path: 'priority', error: 'Priority must be set to allow priority notes.' }
    )
  );

// Optional string
z.formString()

// Required with custom error
z.formString({ required: true, error: 'Name is required' })

// Checks only — no options object needed
z.formString(z.maxLength(100, 'Too long'), z.regex(/^\w+$/, 'Letters only'))

// Required with options and checks
z.formString({ required: true, error: 'Required' }, z.maxLength(50))

// Strip empty strings from toObject() output
z.formString({ allowEmpty: false })

// Use built-in regex patterns from z.regexes instead of writing your own
z.formString({ required: true, error: 'Email is required' }, z.regex(z.regexes.email, 'Invalid email address'))
z.formString(z.regex(z.regexes.e164, 'Must be in international format, e.g. +12125551234'))

// Optional number
z.formNumber()

// Required with custom error
z.formNumber({ required: true, error: 'Age is required' })

// Checks only — no options object needed
z.formNumber(z.gte(0, 'Must be positive'), z.lte(150))

// Required with options and checks
z.formNumber({ required: true, error: 'Required' }, z.gte(18, 'Must be 18 or older'))

// Optional — value is boolean or ''
z.formBoolean()

// Required — must be a boolean
z.formBoolean({ required: true })

// Optional date — defaults to 'yyyy-MM-dd' parsing
z.formDate()

// Custom display format
z.formDate({ dateFormat: 'MM/dd/yyyy' })

// Required with custom format and range check
z.formDate(
  { required: true, dateFormat: 'MM/dd/yyyy', error: 'Date is required' },
  z.gte(new Date(1900, 0, 1), 'Date too far in the past')
)

// Checks only — no options object needed
z.formDate(z.gte(new Date(2000, 0, 1), 'Must be after year 2000'))

// Optional — 'active' | 'inactive' | 'pending' | ''
z.formValues(['active', 'inactive', 'pending'])

// Required — '' is invalid; type is 'active' | 'inactive' | 'pending'
z.formValues(['active', 'inactive', 'pending'], { required: true, error: 'Select a status' })

// Required array of strings
z.formArray(z.string())

// With length constraints
z.formArray(z.formString(), { minLength: 1, maxLength: 10, lengthError: 'Must have 1–10 tags' })

// Optional — may be undefined
z.formArray(z.formNumber(), { required: false })

// Shorthand — second argument is the error string
z.validate(
  (data) => data.endDate > data.startDate,
  'End date must be after start date'
)

// With path — error is stored under 'endDate'
z.validate(
  (data) => !data.endDate || data.endDate > data.startDate,
  { path: 'endDate', error: 'End date must be after start date' }
)

// With condition — skips this check when 'startDate' already has an error
z.validate(
  (data) => data.endDate > data.startDate,
  {
    condition: (errors) => !errors.some((e) => e.pathNotation === 'startDate'),
    path: 'endDate',
    error: 'End date must be after start date',
  }
)

// Attach to an object schema
const schema = z
  .strictObject({ startDate: z.formDate(), endDate: z.formDate() })
  .check(
    z.validate(
      (data) => !data.endDate || !data.startDate || data.endDate > data.startDate,
      { path: 'endDate', error: 'End date must be after start date' }
    )
  );

const schema = z.strictObject({
  participants: z.formArray(
    z.object({ role: z.formValues(['owner', 'member']), name: z.formString() })
  ).check(
    z.someItem(
      (item) => item.role === 'owner',
      'At least one participant must be an owner'
    )
  ),
});

const schema = z.strictObject({
  prices: z.formArray(z.formNumber()).check(
    z.everyItem((price) => price === '' || price > 0, 'All prices must be positive')
  ),
});

// Unique primitive strings — ignore blanks
z.formArray(z.formString()).check(
  z.uniqueItems(false, { error: 'Duplicate tag', ignoreValues: [''] })
)

// Unique by a property — error appears at the duplicate item's 'email' field
z.formArray(z.object({ email: z.formString(), name: z.formString() })).check(
  z.uniqueItems(false, {
    mapFn: (item) => item.email,
    elementPath: ['email'],
    error: 'Email must be unique',
    ignoreValues: [''],
  })
)

// Deep equality for object items
z.formArray(z.object({ x: z.formNumber(), y: z.formNumber() })).check(
  z.uniqueItems(true, { error: 'Duplicate coordinate' })
)

import { useFormState, z, convert } from 'form-state';

const STATUS_VALUES = ['active', 'inactive', 'pending'] as const;

const schema = z.strictObject({
  name: z.formString({ required: true, error: 'Name is required' }).with(z.describe('Name')),
  email: z.formString().with(z.describe('Email')),
  status: z.formValues(STATUS_VALUES).with(z.describe('Status')),
  isAdmin: z.formBoolean({ required: true }).with(z.describe('Admin')),
}).with(z.describe('Profile'));

export function ProfileForm() {
  const {
    formState,
    formStatus,
    formActions,
    formHandlers,
    formHooks,
    Form,
  } = useFormState(schema, {
    initialData: { name: 'Alice' },
  });

  const handleSubmit = formHandlers.handleSubmit(async (submitState) => {
    if (!submitState.valid) return submitState.errors;
    await saveProfile(submitState.data);
    return true;
  });

  return (
    <Form action={handleSubmit}>
      <h2>{formState.descriptions['']}</h2> {/* 'Profile' */}

      <label>
        {formState.descriptions.name}
        <input
          type="text"
          value={formState.data.name}
          onChange={(e) => formActions.change('name', e.target.value)}
          onBlur={() => formActions.touch('name')}
        />
        {formState.errors.name && <span>{formState.errors.name}</span>}
      </label>

      <label>
        {formState.descriptions.email}
        <input
          type="email"
          value={formState.data.email}
          onChange={(e) => formActions.change('email', e.target.value)}
        />
      </label>

      <label>
        {formState.descriptions.status}
        <select
          value={formState.data.status}
          onChange={(e) =>
            formActions.change('status', convert.toLiteral(e.target.value, STATUS_VALUES))
          }
          onBlur={() => formActions.touch('status')}
        >
          <option value="">Select status…</option>
          <option value="active">Active</option>
          <option value="inactive">Inactive</option>
          <option value="pending">Pending</option>
        </select>
        {formState.errors.status && <span>{formState.errors.status}</span>}
      </label>

      {/* Radio buttons — alternative rendering of the same field */}
      <fieldset onBlur={() => formActions.touch('status')}>
        <legend>{formState.descriptions.status}</legend>
        {STATUS_VALUES.map((status) => (
          <label key={status}>
            <input
              type="radio"
              value={status}
              checked={formState.data.status === status}
              onChange={(e) =>
                formActions.change('status', convert.toLiteral(e.target.value, STATUS_VALUES))
              }
            />
            {status}
          </label>
        ))}
        {formState.errors.status && <span>{formState.errors.status}</span>}
      </fieldset>

      <label>
        <input
          type="checkbox"
          checked={formState.data.isAdmin}
          onChange={(e) => formActions.change('isAdmin', e.target.checked)}
        />
        {formState.descriptions.isAdmin}
      </label>

      <button type="submit" disabled={formStatus.submitting}>
        {formStatus.submitting ? 'Saving…' : 'Save'}
      </button>
    </Form>
  );
}

const schema = z.strictObject({
  user: z.object({
    age: z.formNumber(),
    name: z.formString(),
  }),
});

const { formActions, formState } = useFormState(schema);

// ✅ Correct — TypeScript knows 'age' accepts number | ''
formActions.change((path) => path.user.age, 30);

// ✅ Correct — TypeScript knows 'name' accepts string
formActions.change((path) => path.user.name, 'Alice');

// ❌ Type error — 'user.age' is number | '', not string
formActions.change((path) => path.user.age, 'hello');

// ❌ Type error — 'user.typo' does not exist on the schema
formActions.change((path) => path.user.typo, 'value');

formState.data.name              // string
formState.data.age               // number | ''
formState.data.info.address.city // string (nested)
formState.data.tags              // string[]
formState.data.tags[0]           // string

// Top-level field — direct property access
formState.errors.name                              // 'Name is required' | undefined

// Nested field — use .get() with a path expression
formState.errors.get((path) => path.info.age)           // string | undefined
formState.errors.get((path) => path.notes[index].text)  // string | undefined

// Manual errors set via setError()
formState.errors.getManual('_serverError')

// All current errors
formState.errors.getAll()    // string[]  — all messages
formState.errors.getKeys()   // string[]  — e.g. ['name', 'info.age']

// Direct access for top-level fields
formState.dirty.name            // true after first change
formState.touched.name          // true after blur / explicit touch call
formState.required.name         // derived from schema — never changes

// .get() for nested fields
formState.dirty.get((path) => path.info.address.city)
formState.touched.get((path) => path.notes[index].text)
formState.required.get((path) => path.info.age)

// Enumerate all keys that are currently truthy
formState.dirty.getKeys()       // ['name', 'info.age', ...]
formState.touched.getKeys()

// Get the full range object
const ageRange = formState.ranges.get((path) => path.age);
// { type: 'range', format: 'integer', min: 0, max: 150 }

// Direct min/max helpers accept both forms
formState.ranges.getMin('age')              // 0
formState.ranges.getMax((path) => path.age)      // 150
formState.ranges.getMax('name')             // 50  (string maxLength)

// Wire directly to input attributes
<input
  type="number"
  min={formState.ranges.getMin((path) => path.age)}
  max={formState.ranges.getMax((path) => path.age)}
/>
<input
  type="text"
  maxLength={formState.ranges.getMax('name')}
/>

// z.describe() values are available at runtime
formState.descriptions.name                         // 'Full Name'
formState.descriptions.get((path) => path.info.age)      // 'Age'
formState.descriptions.get((path) => path.notes[0])      // 'Note'  (index normalised to [0])

// Patterns (from z.regex()) as raw strings for input[pattern]
formState.patterns.name                             // '^[\\w\\s\'-]+$'
formState.patterns.get((path) => path.info.id)

// Use in JSX
<label>{formState.descriptions.get((path) => path.auto.modelId)}</label>

const payload = schema.toObject(formState.data);
// uuid symbols stripped, optional empty strings omitted
await api.post('/users', payload);

<button type="submit" disabled={!formStatus.dirty || formStatus.submitting}>
  Save changes
</button>

{formStatus.valid === false && (
  <p>Please fix the errors above before saving.</p>
)}

const schema = z.strictObject({
  name: z.formString({ required: true }).with(z.describe('Full Name')),
  age:  z.formNumber(z.gte(0), z.lte(150)).with(z.describe('Age')),
  info: z.object({
    email: z.formString().with(z.describe('Email Address')),
  }),
});

// Top-level field — direct property access
<label htmlFor="name">{formState.descriptions.name}</label>

// Nested field — use .get() with a path expression
<label htmlFor="email">
  {formState.descriptions.get((path) => path.info.email)}
</label>

// Array item field — index is normalised to [0] in descriptions
<label>{formState.descriptions.get((path) => path.notes[0].text)}</label>

import { useFormState, z, convert } from "form-state";

const schema = z.strictObject({
  username: z
    .formString(z.minLength(3, 'Too short'), z.maxLength(20, 'Too long'))
    .with(z.describe('Username')),
  age: z
    .formNumber(z.gte(18, 'Must be 18+'), z.lte(120))
    .with(z.describe('Age')),
  birthDate: z
    .formDate({ dateFormat: 'yyyy-MM-dd' }, z.gte(new Date(1900, 0, 1)))
    .with(z.describe('Birth Date')),
  bio: z
    .formString(z.maxLength(500, 'Too long'))
    .with(z.describe('Bio')),
  tags: z
    .formArray(z.string(), { minLength: 1, maxLength: 5 })
    .with(z.describe('Tags')),
});

// ── Text input ─────────────────────────────────────────────────
<div>
  <label htmlFor="username">{formState.descriptions.username}</label>
  <input
    id="username"
    type="text"
    value={formState.data.username}
    minLength={formState.ranges.getMin('username')}   // 3
    maxLength={formState.ranges.getMax('username')}   // 20
    required={formState.required.username}
    onChange={(e) => formActions.change('username', e.target.value)}
    onBlur={() => formActions.touch('username')}
  />
</div>

// ── Number input ───────────────────────────────────────────────
<div>
  <label htmlFor="age">{formState.descriptions.age}</label>
  <input
    id="age"
    type="number"
    value={formState.data.age}
    min={formState.ranges.getMin('age')}              // 18
    max={formState.ranges.getMax('age')}              // 120
    required={formState.required.age}
    onChange={(e) => formActions.change('age', convert.toInt(e.target.value))}
    onBlur={() => formActions.touch('age')}
  />
</div>

// ── Date input ─────────────────────────────────────────────────
const rawDate = formState.data.birthDate;
const dateValue = rawDate instanceof Date ? formatDate(rawDate, 'yyyy-MM-dd') : rawDate;
const minDate = formState.ranges.getMin((path) => path.birthDate);
const minAttr = minDate instanceof Date ? formatDate(minDate, 'yyyy-MM-dd') : undefined;

<div>
  <label htmlFor="birthDate">{formState.descriptions.birthDate}</label>
  <input
    id="birthDate"
    type="date"
    value={dateValue}
    min={minAttr}
    onChange={(e) => formActions.change('birthDate', convert.toDate(e.target.value, { format: 'yyyy-MM-dd' }))}
    onBlur={() => formActions.touch('birthDate')}
  />
</div>

// ── Textarea ───────────────────────────────────────────────────
<div>
  <label htmlFor="bio">{formState.descriptions.bio}</label>
  <textarea
    id="bio"
    value={formState.data.bio}
    maxLength={formState.ranges.getMax('bio')}        // 500
    onChange={(e) => formActions.change('bio', e.target.value)}
  />
  <small>{formState.data.bio.length} / {formState.ranges.getMax('bio')}</small>
</div>

// ── Array length guard ─────────────────────────────────────────
<button
  onClick={() => formActions.array.append('tags', [''])}
  disabled={formState.data.tags.length >= (formState.ranges.getMax('tags') ?? Infinity)}
>
  Add tag {formState.data.tags.length} / {formState.ranges.getMax('tags')}
</button>

// Top-level field
formState.required.name                          // true | false

// Nested field
formState.required.get((path) => path.info.age)       // true | false

// In JSX — drives the attribute and the visible asterisk together
<label htmlFor="name">
  {formState.descriptions.name}
  {formState.required.name && <span> *</span>}
</label>
<input
  id="name"
  type="text"
  required={formState.required.name}
  value={formState.data.name}
  onChange={(e) => formActions.change('name', e.target.value)}
/>

// Top-level field
formState.patterns.id                            // "^\d+(-\d+)?$" | undefined

// Nested field
formState.patterns.get((path) => path.info.code)      // string | undefined

// In JSX
<input
  type="text"
  value={formState.data.id}
  pattern={formState.patterns.id}
  title="Must be a number or number range, e.g. 10-20"
  onChange={(e) => formActions.change('id', e.target.value)}
/>

// Read — top-level and nested
formState.touched.name                           // boolean
formState.touched.get((path) => path.info.age)        // boolean

// Typical pattern: show error only after interaction
{formState.touched.name && formState.errors.name && (
  <span role="alert">{formState.errors.name}</span>
)}

// Set on blur (most common)
<input onBlur={() => formActions.touch('name')} />

// Set immediately on change — good for selects and checkboxes
formActions.change((path) => path.category, value, { touch: true });

// Touch a field programmatically without changing its value
formActions.touch('name');
formActions.touch((path) => path.notes[index].text);

// Touch with optional validation
formActions.touch('name', { validate: true });

// Inspect which fields have been touched
formState.touched.getKeys()                      // ['name', 'info.age', ...]
formStatus.touched                               // true if any field is touched

function TextField({ name }: { name: keyof FormSchema }) {
  const { formState, formActions, formClasses } = useSchemaFormState();

  const label     = formState.descriptions[name];
  const value     = formState.data[name] as string;
  const error     = formState.errors[name];
  const touched   = formState.touched[name];
  const maxLength = formState.ranges.getMax(name);
  const minLength = formState.ranges.getMin(name);
  const pattern   = formState.patterns[name];
  const required  = formState.required[name];

  return (
    <div className={formClasses(name)}>
      <label htmlFor={name}>
        {label}
        {required && <span aria-hidden> *</span>}
      </label>
      <input
        id={name}
        type="text"
        value={value}
        minLength={minLength}
        maxLength={maxLength}
        pattern={pattern}
        required={required}
        aria-invalid={touched && Boolean(error)}
        aria-describedby={error ? `${name}-error` : undefined}
        onChange={(e) => formActions.change(name, e.target.value)}
        onBlur={() => formActions.touch(name)}
      />
      {touched && error && (
        <span id={`${name}-error`} role="alert">{error}</span>
      )}
      {maxLength && (
        <small>{value.length} / {maxLength}</small>
      )}
    </div>
  );
}

// Append one or more items
formActions.array.append('tags', ['react', 'typescript']);
formActions.array.append((path) => path.notes, [{ text: '', typeId: '' }], { validate: true });

// Insert at a specific position
formActions.array.insert('tags', 0, 'featured');

// Update item at index
formActions.array.update('tags', 1, 'updated-tag');

// Swap two items
formActions.array.swap('tags', 0, 2);

// Remove by index
formActions.array.remove('tags', 0);

// Remove by predicate
formActions.array.remove('tags', (tag) => tag === 'deprecated');
formActions.array.remove((path) => path.notes, (note) => note.text === '');

// Clear the array
formActions.array.clear('tags');

const schema = z.strictObject({
  notes: z.formArray(
    z.object({
      uniqueId: z.symbol(),      // auto UUID — use as React key
      typeId: z.formNumber({ required: true, error: 'Note type is required.' }),
      text: z.formString({ required: true }, z.maxLength(100)),
    }),
    { minLength: 2, maxLength: 5 }
  ),
});

// In your component:
{formState.data.notes.map((note, index) => (
  <div key={note.uniqueId.toString()}>
    <input
      value={note.text}
      onChange={(e) =>
        formActions.change((path) => path.notes[index].text, e.target.value, { touch: true })
      }
    />
    {formState.errors.get((path) => path.notes[index].text) && (
      <span>{formState.errors.get((path) => path.notes[index].text)}</span>
    )}
    <button onClick={() => formActions.array.remove('notes', index)}>
      Remove
    </button>
  </div>
))}

<button
  onClick={() => formActions.array.append('notes', [{ text: '', typeId: '' }])}
  disabled={formState.data.notes.length >= formState.ranges.getMax('notes')}
>
  Add note
</button>

// Validate the full schema
formActions.validate();

// Validate and mark as submitted on success
formActions.validate({ submit: true });

// Validate with a custom async check (e.g. server-side uniqueness)
formActions.validate(
  async () => {
    const taken = await api.checkUsername(formState.data.username);
    return taken ? { username: 'Username is already taken' } : true;
  },
  { submit: true }
);

<input
  value={formState.data.email}
  onChange={(e) => formActions.change('email', e.target.value)}
  onBlur={() => formActions.touch('email')}
/>

{/* Only shown after blur */}
{formState.touched.email && formState.errors.email && (
  <p className="error">{formState.errors.email}</p>
)}

// Select / dropdown — touch immediately on pick
formActions.change((path) => path.auto.modelId, selectedId, { touch: true });

// Checkbox — touch and validate on click
formActions.change((path) => path.priority, e.target.checked, { touch: true });

// Radio buttons — top-level string form is fine here
formActions.change('sendEmail', 'yes', { touch: true });

useFormState(schema, {
  initialData: existingRecord,
  initialTouched: ['name', 'email', (path) => path.info.age],
});

import { type SubmitState } from 'form-state';

const handleSubmit = formHandlers.handleSubmit(
  async (submitState: SubmitState<typeof schema>, formData: FormData) => {
    // Schema validation failed — return the error map
    if (!submitState.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return submitState.errors;
    }

    // submitState.data is fully typed and validated here
    try {
      await fetch('/api/profile', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(submitState.data),
      });
      return true; // success
    } catch (err) {
      return { _serverError: 'Something went wrong. Please try again.' };
    }
  },
  {
    onSuccess: ({ data, formData }: SubmitSuccessState<typeof schema>) => {
      router.push('/dashboard');
    },
    onError: (state, status) => {
      formActions.focusOnFirstError();
    },
  }
);

return <Form action={handleSubmit}>...</Form>;

formActions.focusOnFirstError({ selectText: true });

// Or focus a specific element
formActions.focus('email', { selectText: true });

// Focus only if the field has an error
formActions.focus('email', { errorKey: 'email' });

const { formState, formStatus, formActions, formHandlers } = useFormState(schema);

const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();

  formActions.validate(
    async () => {
      // Optional: async cross-field or server-side check
      const taken = await api.checkEmail(formState.data.email);
      return taken ? { email: 'Email already registered' } : true;
    },
    {
      submit: true,
      callback: (state, status) => {
        if (status.valid) {
          api.save(schema.toObject(state.data));
        } else {
          formActions.focusOnFirstError({ selectText: true });
        }
      },
    }
  );
};

return (
  <form
    noValidate
    onSubmit={handleSubmit}
    onReset={formHandlers.handleReset}
  >
    <input
      value={formState.data.name}
      onChange={(e) => formActions.change('name', e.target.value)}
      onBlur={() => formActions.touch('name')}
    />
    {formState.errors.name && <span>{formState.errors.name}</span>}

    <button type="submit" disabled={formStatus.submitting}>Save</button>
    <button type="reset">Reset</button>
  </form>
);

// name="email"
//   formData.get('email')
// name={inferName(path => path.info.age)}
//   formData.get('info["age"]')
// name={inferName(path => path.tags[0], 'dot')}
//   formData.get('tags.0')

const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) return state.errors;

  // Raw string from FormData — useful for fields outside the schema
  const redirectTo = formData.get('redirectTo') as string | null;
  const age        = formData.get('info["age"]') as string | null;

  await api.save(state.data);
  return true;
};

// Two submit buttons with the same name but different values
<Form action={handleSubmit}>
  <button name="action" value="save">Save draft</button>
  <button name="action" value="publish">Publish</button>
</Form>

// In your handler — formData always carries the clicked button's value
const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) return state.errors;

  const action = formData.get('action'); // 'save' | 'publish'

  if (action === 'publish') {
    await api.publish(state.data);
  } else {
    await api.saveDraft(state.data);
  }
  return true;
};

import { useFormStatus } from 'react-dom';

// Must be a child of the <form> element — not the same component
export function FormMask() {
  const { pending } = useFormStatus();

  if (!pending) return null;

  return (
    <div
      role="status"
      aria-label="Saving…"
      style={{
        position: 'absolute',
        inset: 0,
        display: 'grid',
        placeItems: 'center',
        background: 'rgba(0,0,0,0.4)',
        zIndex: 10,
      }}
    >
      <Spinner />
    </div>
  );
}

// Use it inside <Form>
<Form action={action} style={{ position: 'relative' }}>
  <FormMask />
  {/* ... */}
</Form>

import { formDataEncode } from 'form-state';

const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) return state.errors;

  // Encode all entries as a URL-encoded string
  const body = formDataEncode(formData).toString();
  // "name=Alice&info%5B%22age%22%5D=30"  (bracket notation — useFormState default)
  // "name=Alice&info.age=30"  (dot notation — pass 'dot' as nameFormat arg,
  //                            or use inferName(path, 'dot'))

  // Omit specific fields (e.g. internal tracking values)
  const bodyClean = formDataEncode(formData, ['csrf', 'action']).toString();

  await fetch('/api/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body,
  });
  return true;
};

// Set by field key
formActions.setError('email', 'This email address is already registered');

// Set by path expression — nested field inside an array item
formActions.setError((path) => path.notes[index].text, '666 is not allowed as note text');

// Set a form-level error (arbitrary string key)
formActions.setError('_serverError', 'Something went wrong. Please try again.');

// Clear a specific manual error (pass null, undefined, or call with one argument)
formActions.setError('email', null);
formActions.setError((path) => path.notes[index].text); // clears it

// Clear all manual errors
formActions.clearManualErrors();

// Clear only errors matching a predicate
formActions.clearManualErrors({
  predicate: (key) => key.startsWith('_'),
});

{formState.errors.getManual('_serverError') && (
  <div className="form-error">
    {formState.errors.getManual('_serverError')}
  </div>
)}

// Set initial mode
useFormState(schema, { initialMode: 'readOnly' });

// Switch at runtime
formActions.setMode('editable');
formActions.setMode('readOnly');
formActions.setMode('disabled');

const { formState, formStatus, formActions } = useSchemaFormState();
const { readOnly } = formStatus;

// ── Select / dropdown ──────────────────────────────────────────
{readOnly ? (
  <input
    type="text"
    readOnly
    tabIndex={-1}
    value={noteTypes.find((noteType) => noteType.value === note.typeId)?.label ?? ''}
    autoComplete="off"
  />
) : (
  <Select
    options={noteTypes}
    value={note.typeId}
    onChange={(opt) =>
      formActions.change((path) => path.notes[index].typeId, opt?.value ?? '', { touch: true })
    }
  />
)}

// ── Checkbox ───────────────────────────────────────────────────
{readOnly ? (
  <input
    type="text"
    readOnly
    tabIndex={-1}
    value={data.priority === true ? 'Yes' : data.priority === false ? 'No' : 'N/A'}
    autoComplete="off"
  />
) : (
  <input
    id="priority"
    type="checkbox"
    checked={Boolean(data.priority)}
    onChange={(e) => formActions.change((path) => path.priority, e.target.checked, { touch: true })}
  />
)}

// ── Radio buttons ──────────────────────────────────────────────
{readOnly ? (
  <input type="text" readOnly tabIndex={-1} value={data.sendEmail === 'yes' ? 'Yes' : 'No'} />
) : (
  <span role="group">
    <label>
      <input type="radio" value="yes"
        onChange={() => formActions.change('sendEmail', 'yes', { touch: true })} />
      Yes
    </label>
    <label>
      <input type="radio" value="no"
        onChange={() => formActions.change('sendEmail', 'no', { touch: true })} />
      No
    </label>
  </span>
)}

// ── Array controls ─────────────────────────────────────────────
{!readOnly && (
  <button onClick={() => formActions.array.remove((path) => path.notes, index)}>
    Remove
  </button>
)}
{!readOnly && (
  <button onClick={() => formActions.array.append('notes', [emptyNote])}>
    Add note
  </button>
)}

<Form
  action={formHandlers.handleSubmit(onSubmit)}
  data-readonly={formStatus.readOnly}  // CSS hook for styling
>
  <fieldset disabled={formStatus.disabled}>
    <IdInput />
    <NoteInputs />
    <AutoSelects />
    {!formStatus.readOnly && <Footer />}
  </fieldset>
</Form>

import { type FormMode } from 'form-state';

function ModeSelector({
  mode,
  onChange,
}: {
  mode: FormMode;
  onChange: (mode: FormMode) => void;
}) {
  return (
    <div>
      {(['editable', 'readOnly', 'disabled'] as FormMode[]).map((option) => (
        <label key={option}>
          <input
            type="radio"
            checked={mode === option}
            onChange={() => onChange(option)}
          />
          {option}
        </label>
      ))}
    </div>
  );
}

// In parent:
<ModeSelector
  mode={formStatus.mode}
  onChange={(m) => formActions.setMode(m)}
/>

// Generates e.g.: "form-state__error form-state__touched form-state__required"

<div className={formClasses('name')}>
  <label>Name</label>
  <input ... />
  <span>{formState.errors.name}</span>
</div>

// Arrow function path expression — works for nested fields too
<label className={formClasses((path) => path.info.name)}>
  {formState.descriptions.get((path) => path.info.name)}
</label>

// Custom prefix per-call
formClasses('name', undefined, { prefix: 'my-form' })
// "my-form__error my-form__required"

useFormState(schema, { CSSPrefix: 'my-form' });

// app-schema.ts
import { useFormStateContext, z } from 'form-state';

export const formSchema = z.strictObject({ /* ... */ });
export type FormSchema = z.infer<typeof formSchema>;

// One typed hook — used everywhere in the form tree
export const useSchemaFormState = () => useFormStateContext(formSchema);

// NameField.tsx — leaf component, no props needed
import { useSchemaFormState } from './app-schema';

export function NameField() {
  const { formState, formActions, formClasses } = useSchemaFormState();

  return (
    <div>
      <label className={formClasses((path) => path.info.name)}>
        {formState.descriptions.get((path) => path.info.name)}
      </label>
      <input
        type="text"
        value={formState.data.info.name}
        maxLength={formState.ranges.getMax((path) => path.info.name)}
        onChange={(e) => formActions.change((path) => path.info.name, e.target.value)}
        onBlur={() => formActions.touch((path) => path.info.name)}
      />
      {formState.errors.get((path) => path.info.name) && (
        <p>{formState.errors.get((path) => path.info.name)}</p>
      )}
    </div>
  );
}

// AppForm.tsx — root form component wrapped with formConnect
import { formConnect } from 'form-state';
import { formSchema } from './app-schema';

function AppForm({ onSubmitted }: { onSubmitted: () => void }) {
  const { Form, formHandlers } = useSchemaFormState();

  return (
    <Form action={formHandlers.handleSubmit(onSubmit, { onSuccess: onSubmitted })}>
      <fieldset>
        <NameField />
        <AgeField />
      </fieldset>
      <button type="submit">Save</button>
    </Form>
  );
}

export default formConnect({
  schema: formSchema,
  confirmDirtyStateNavigation: true,  // warn on unsaved navigation
  watch: true,                        // enable useWatch
})(AppForm);

import { SecureInput } from 'form-state';

<SecureInput
  type="password"
  onSecureChange={(value) => {
    // 'value' is the real plaintext — never touches the DOM
    formActions.change('password', value);
  }}
  onSecureBlur={(value) => {
    formActions.change('password', value, { touch: true });
  }}
/>

const { formState, formHooks } = useFormState(schema);

// Extract a field as-is
const selectName = formHooks.useSelector(
  state => state.name,
  name => name
);

// Derive a boolean from a field
const selectIsAdult = formHooks.useSelector(
  state => state.age,
  age => typeof age === 'number' && age >= 18
);

selectName(formState.data)     // string
selectIsAdult(formState.data)  // boolean

// Filters the items array — reruns only when items changes
const selectActiveItems = formHooks.useSelector(
  state => state.items,
  items => items.filter(item => item.active)
);

// Counts the filtered list — reruns only when selectActiveItems output changes
const selectActiveCount = formHooks.useSelector(
  selectActiveItems,
  items => items.length
);

// Maps names — also reads from the already-filtered list
const selectActiveNames = formHooks.useSelector(
  selectActiveItems,
  items => items.map(item => item.name)
);

selectActiveCount(formState.data)  // number
selectActiveNames(formState.data)  // string[]

const schema = z.strictObject({
  orders: z.array(
    z.object({
      product: z.formString(),
      quantity: z.formNumber(),
      unitPrice: z.formNumber(),
      shipped: z.formBoolean(),
    })
  ),
  discountPct: z.formNumber(),
});

const { formState, formHooks } = useFormState(schema);

// Select unshipped orders
const selectPendingOrders = formHooks.useSelector(
  state => state.orders,
  orders => orders.filter(order => !order.shipped)
);

// Combine the filtered list with the discount to compute an order summary
const selectOrderSummary = formHooks.useSelector(
  [selectPendingOrders, state => state.discountPct], // array of selectors
  (pending, discountPct) => {
    const subtotal = pending.reduce((sum, o) => sum + o.quantity * o.unitPrice, 0);
    const discount = typeof discountPct === 'number' ? discountPct / 100 : 0;
    return {
      count: pending.length,
      subtotal,
      total: subtotal * (1 - discount),
    };
  }
);

const summary = selectOrderSummary(formState.data);
// { count: number; subtotal: number; total: number }

formActions.change('search', inputValue, {
  debounceIntervalMs: 400,
  callback: (state, status) => {
    // Fires 400ms after the last keystroke
    performSearch(state.data.search);
  },
});

// Arrow function path — nested field
formActions.change((path) => path.notes[index].text, e.target.value, {
  debounceIntervalMs: 500,
  touch: true,
  callback: (state: FormState<FormSchema>) => {
    // Custom async check after user stops typing
    if (state.data.notes[index].text === '666') {
      formActions.setError((path) => path.notes[index].text, 'Not allowed');
    } else {
      formActions.setError((path) => path.notes[index].text);
    }
  },
});

import { type StateChangeListener } from 'form-state';

const listener: StateChangeListener<FormSchema> = ({ type, data }) => {
  console.info(type, data);
};

function AppForm() {
  formHooks.useListener(listener);
  // ...
}

// Enable watching at the hook / formConnect level
useFormState(schema, { watch: true });
// or: formConnect({ schema, watch: true })(MyForm)

// Watch a field by its inferName value, with an optional transform
const idValue = formHooks.useWatch(
  formActions.inferName((path) => path.id),
  (value) => value.trim()
);

// Use the live value to drive conditional rendering
{/^666(-\d*)?$/.test(idValue) && <DevilIcon />}

// Watch with a more complex transform — only keep valid values
const cleanId = formHooks.useWatch(
  formActions.inferName((path) => path.id),
  (val) => (/^\d+$|^(\d+-\d+)$/.test(val) ? val : '')
);

// Bracket format (default) — infers: info["age"]
formActions.inferName((path) => path.info.age)

// Dot format — infers: info.age
formActions.inferName((path) => path.info.age, 'dot')

// Top-level string — always just the key itself
formActions.inferName('name')

// Uncontrolled input + useWatch combo
<input
  name={formActions.inferName((path) => path.id)}
  defaultValue={formState.data.id}
  onChange={(e) => formActions.change((path) => path.id, e.target.value)}
/>

// useWatch subscribes by the same name string
const watched = formHooks.useWatch(formActions.inferName((path) => path.id));

// Reading back from FormData on submit
const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  // bracket key (default format)
  formData.get('info["age"]');    // value of info.age
  // dot key
  formData.get('info.age');       // only if that field used 'dot' format
};

const { Form, formActions } = useFormState(schema, {
  inferredNameFormat: 'dot', // all inferName calls default to dot notation
});

import { convert } from 'form-state';

// Safe numeric parsing — returns the number or '' if invalid
convert.toInt('42')          // 42
convert.toFloat('3.14')      // 3.14
convert.toInt('abc')         // ''

// Optional number to number type conversion
convert.asNumber(1);          // 1
convert.asNumber('');         // 0
convert.asNumber('', 100.0);  // 100.0

// Date parsing with format string
convert.toDate('12/31/2024', { format: 'MM/dd/yyyy' })  // Date object

// Optional boolean to boolean type conversion
convert.asBoolean(true);      // true
convert.asBoolean('', false); // false
convert.asBoolean('', true);  // true

// Boolean coercion
convert.toBoolean('true')     // true
convert.toBoolean('0')        // false

// Validated literal — returns the value or '' if not in set
convert.toLiteral('active', ['active', 'inactive'])  // 'active'
convert.toLiteral('other',  ['active', 'inactive'])  // ''

import { formatDate } from 'form-state';

const date = formState.data.birthDate; // Date | ''

if (date instanceof Date) {
  formatDate(date, 'MM/dd/yyyy')   // '12/31/2024'
  formatDate(date, 'yyyy-MM-dd')   // '2024-12-31'
}

import { safeParseDate } from 'form-state';

const { success: startDateSuccess, date: startDate } = safeParseDate('2020-12-01'); // yyyy-MM-dd
// startDateSuccess: true
// startDate: new Date(2020, 11, 1)

const { date: endDate } = safeParseDate('12/31/2020', 'MM/dd/yyyy');

const { success: finalDateSuccess, date: finalDate } = safeParseDate('abcd1234', 'MM/dd/yyyy');
// finalDateSuccess: false
// finalDate: null

// Mark a file as pending upload
formActions.setDirty('#avatar', true);
formState.dirty.get('#avatar')   // true
formStatus.dirty                 // true (includes #avatar)

// Clear after upload completes
formActions.setDirty('#avatar', false);

import { parseState } from 'form-state';

const result = parseState(formSchema, apiResponse);

if (result.success) {
  formActions.replace(result.data, { validate: true });
} else {
  // result.errors.getAll() — array of validation messages
  // result.errors.getKeys() — failed field paths
  console.warn('API data has validation issues:', result.errors.getAll().join(' | '));
  // Still use the coerced data if errors are non-critical
  formActions.replace(result.data);
}

"use server";

import { parseState, z } from "form-state";
import { schema } from "./contact-form";

export async function submitContact(formData: z.infer<typeof schema>): Promise<void> {
  const result = parseState(schema, formData, true);

  if (!result.success) {
    throw new Error(result.errors.getAll().join(" | "));
  }

  await db.contacts.create({ data: result.data });
}

"use client";

import { useFormState, z } from "form-state";
import { submitContact } from "./actions";

const schema = z.object({
  name: z.formString({ required: true, error: "Name is required" }),
  email: z.formString(
    { required: true, error: "Email is required" },
    z.regex(z.regexes.email, "Enter a valid email"),
  ),
  message: z.formString(
    { required: true, error: "Message is required" },
    z.minLength(10, "Must be at least 10 characters"),
  ),
  agreeToTerms: z.formBoolean({ required: true, error: "Agreement is required" })
    .check(z.validate((v) => v === true, "You must agree to continue")),
});

export default function ContactForm() {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema);

  const handleSubmit = formHandlers.handleSubmit(async (state) => {
    if (!state.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return {};
    }

    try {
      await submitContact(state.data);
      return true;
    } catch (ex) {
      return { _serverError: ex instanceof Error ? ex.message : "Server error" };
    }
  });

  return (
    <Form action={handleSubmit}>
      {errors.getManual("_serverError") && (
        <p className="error">{errors.getManual("_serverError")}</p>
      )}

      <label>
        Name
        <input
          type="text"
          name={formActions.inferName("name")}
          defaultValue={data.name}
          onBlur={(e) => formActions.change("name", e.target.value, { touch: true })}
        />
        {errors.name && <span>{errors.name}</span>}
      </label>

      <label>
        Email
        <input
          type="email"
          name={formActions.inferName("email")}
          defaultValue={data.email}
          onBlur={(e) => formActions.change("email", e.target.value, { touch: true })}
        />
        {errors.email && <span>{errors.email}</span>}
      </label>

      <label>
        Message
        <textarea
          name={formActions.inferName("message")}
          defaultValue={data.message}
          onBlur={(e) => formActions.change("message", e.target.value, { touch: true })}
        />
        {errors.message && <span>{errors.message}</span>}
      </label>

      <label>
        <input
          type="checkbox"
          name={formActions.inferName("agreeToTerms")}
          defaultChecked={data.agreeToTerms === true}
          onChange={(e) => formActions.change("agreeToTerms", e.target.checked, { touch: true })}
        />
        I agree to the terms
        {errors.agreeToTerms && <span>{errors.agreeToTerms}</span>}
      </label>

      <button type="submit" disabled={submitting}>
        {submitting ? "Sending…" : "Send"}
      </button>

      <button type="reset" disabled={!dirty}>
        Reset
      </button>
    </Form>
  );
}

// app/contact/page.tsx
import { parseState } from "form-state";
import ContactForm, { schema } from "./contact-form";

export default async function ContactPage() {
  const user = await db.users.findFirst({ where: { id: await getSessionUserId() } });
  const result = parseState(schema, user);

  if (!result.success) {
    throw new TypeError("Unexpected user data shape");
  }

  return <ContactForm user={result.data} />;
}

"use client";

import { useFormState, z } from "form-state";
import { submitContact } from "./actions";

// schema definition unchanged …

export default function ContactForm({
  user,
}: {
  user?: z.infer<typeof schema>;
}) {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema, { initialData: user });

  // … rest of the component unchanged
}

// app/routes/contact.ts
import type { Route } from "./+types/contact";
import { parseState, z } from "form-state";
import { schema } from "../contact-form";

export async function action({ request }: Route.ActionArgs) {
  const { data: formData } = await request.json() as { data: z.infer<typeof schema> };
  const result = parseState(schema, formData, true);

  if (!result.success) {
    return Response.json({ error: result.errors.getAll().join(" | ") }, { status: 400 });
  }

  await db.contacts.create({ data: result.data });

  return { success: true };
}

import { useFormState, z } from "form-state";

const schema = z.object({
  name: z.formString({ required: true, error: "Name is required" }),
  email: z.formString(
    { required: true, error: "Email is required" },
    z.regex(z.regexes.email, "Enter a valid email"),
  ),
  message: z.formString(
    { required: true, error: "Message is required" },
    z.minLength(10, "Must be at least 10 characters"),
  ),
  agreeToTerms: z.formBoolean({ required: true, error: "Agreement is required" })
    .check(z.validate((v) => v === true, "You must agree to continue")),
});

export default function ContactForm() {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema);

  const handleSubmit = formHandlers.handleSubmit(async (state) => {
    if (!state.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return {};
    }

    const res = await fetch("/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ data: state.data }),
    });

    if (!res.ok) {
      const error = await res.json() as Error;
      return { _serverError: error?.message ?? "Server error" };
    }

    return true;
  });

  return (
    <Form action={handleSubmit}>
      {errors.getManual("_serverError") && (
        <p className="error">{errors.getManual("_serverError")}</p>
      )}

      <label>
        Name
        <input
          type="text"
          name={formActions.inferName("name")}
          defaultValue={data.name}
          onBlur={(e) => formActions.change("name", e.target.value, { touch: true })}
        />
        {errors.name && <span>{errors.name}</span>}
      </label>

      <label>
        Email
        <input
          type="email"
          name={formActions.inferName("email")}
          defaultValue={data.email}
          onBlur={(e) => formActions.change("email", e.target.value, { touch: true })}
        />
        {errors.email && <span>{errors.email}</span>}
      </label>

      <label>
        Message
        <textarea
          name={formActions.inferName("message")}
          defaultValue={data.message}
          onBlur={(e) => formActions.change("message", e.target.value, { touch: true })}
        />
        {errors.message && <span>{errors.message}</span>}
      </label>

      <label>
        <input
          type="checkbox"
          name={formActions.inferName("agreeToTerms")}
          defaultChecked={data.agreeToTerms === true}
          onChange={(e) => formActions.change("agreeToTerms", e.target.checked, { touch: true })}
        />
        I agree to the terms
        {errors.agreeToTerms && <span>{errors.agreeToTerms}</span>}
      </label>

      <button type="submit" disabled={submitting}>
        {submitting ? "Sending…" : "Send"}
      </button>

      <button type="reset" disabled={!dirty}>
        Reset
      </button>
    </Form>
  );
}

// app/routes/contact.tsx
import type { Route } from "./+types/contact";
import { parseState } from "form-state";
import ContactForm, { schema } from "../contact-form";

export async function loader() {
  const user = await db.users.findFirst({ where: { id: await getSessionUserId() } });
  const result = parseState(schema, user);

  if (!result.success) {
    throw new Response("Unexpected user data shape", { status: 500 });
  }

  return result.data;
}

export default function ContactRoute({ loaderData }: Route.ComponentProps) {
  return <ContactForm user={loaderData} />;
}

import { useFormState, z } from "form-state";

// schema definition unchanged …

export default function ContactForm({
  user,
}: {
  user?: z.infer<typeof schema>;
}) {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema, { initialData: user });

  // … rest of the component unchanged
}

npm install @tanstack/react-query

import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { useFormState, parseState, z, type SchemaDataObject, type SubmitState } from 'form-state';

const DATE_FORMAT = 'MM/dd/yyyy';

const profileSchema = z.strictObject({
  name:        z.formString({ required: true }).with(z.describe('Name')),
  email:       z.formString({ required: true }).with(z.describe('Email')),
  dateOfBirth: z.formDate({ dateFormat: DATE_FORMAT }).with(z.describe('Date of Birth')),
  bio:         z.formString().with(z.describe('Bio')),
});

// Inferred form state shape TypeScript type
type ProfileData = z.infer<typeof profileSchema>;

// Derived API type — empty literals replaced with `undefined`, optional fields use `?`
type ProfileApiData = SchemaDataObject<ProfileData>;

// Your fetch layer — swap for any HTTP client
declare const api: {
  getProfile(userId: string): Promise<ProfileApiData>;
  updateProfile(userId: string, values: ProfileApiData): Promise<void>;
};

function FormError({ error }: { error?: string }) {
  return error ? <span className="field-error">{error}</span> : null;
}

function ProfileForm({ userId }: { userId: string }) {
  const queryClient = useQueryClient();

  // 1. Fetch and validate current server data
  const { data } = useSuspenseQuery({
    queryKey: ['profile', userId],
    queryFn: async () => {
      const apiData = await api.getProfile(userId);

      // Validate the API response against the schema.
      const result = parseState(profileSchema, apiData);

      if (result.success) {
        return result.data;
      } else {
        throw new Error(result.errors.getAll().join(' | '));
      }
    },
  });

  // 2. Seed the form — confirmDirtyStateNavigation prompts before unsaved navigation
  const { Form, formState, formStatus, formActions, formHandlers } =
    useFormState(profileSchema, {
      initialData: data,
      confirmDirtyStateNavigation: true,
    });

  // 3. Mutation for saving
  const { mutateAsync } = useMutation({
    mutationFn: (values: ProfileApiData) => api.updateProfile(userId, values),
  });

  // 4. Submit handler — mutateAsync lives inside the async callback
  const handleSubmit = formHandlers.handleSubmit(
    async (submitState: SubmitState<typeof profileSchema>) => {
      if (!submitState.valid) {
        return submitState.errors;
      }

      try {
        await mutateAsync(profileSchema.toObject(submitState.data));
        return true;
      } catch (err) {
        return { _serverError: err instanceof Error ? err.message : 'Save failed.' };
      }
    },
    {
      onSuccess: () => {
        queryClient.invalidateQueries({ queryKey: ['profile', userId] });
      },
    }
  );

  return (
    <Form action={handleSubmit}>
      <FormError error={formState.errors.getManual('_serverError')} />

      <label>
        {formState.descriptions.name}
        {formState.required.name && <span> *</span>}
        <input
          value={formState.data.name}
          required={formState.required.name}
          onChange={(e) => formActions.change('name', e.target.value)}
          onBlur={() => formActions.touch('name')}
        />
        <FormError error={formState.errors.name} />
      </label>

      <label>
        {formState.descriptions.email}
        {formState.required.email && <span> *</span>}
        <input
          type="email"
          value={formState.data.email}
          required={formState.required.email}
          onChange={(e) => formActions.change('email', e.target.value)}
          onBlur={() => formActions.touch('email')}
        />
        <FormError error={formState.errors.email} />
      </label>

      <label>
        {formState.descriptions.dateOfBirth}
        <input
          type="text"
          placeholder={DATE_FORMAT}
          value={formState.data.dateOfBirth}
          onChange={(e) => formActions.change('dateOfBirth', e.target.value)}
          onBlur={() => formActions.touch('dateOfBirth')}
        />
        <FormError error={formState.errors.dateOfBirth} />
      </label>

      <label>
        {formState.descriptions.bio}
        <textarea
          value={formState.data.bio ?? ''}
          onChange={(e) => formActions.change('bio', e.target.value)}
          onBlur={() => formActions.touch('bio')}
        />
      </label>

      <button type="submit" disabled={formStatus.submitting}>Save Changes</button>
    </Form>
  );
}

// Wrap at the call site — Suspense handles loading, ErrorBoundary handles fetch errors
function ProfilePage({ userId }: { userId: string }) {
  return (
    <ErrorBoundary fallback={<ErrorMessage />}>
      <Suspense fallback={<Skeleton />}>
        <ProfileForm userId={userId} />
      </Suspense>
    </ErrorBoundary>
  );
}

const { data } = useSuspenseQuery({
  queryKey: ['profile', userId],
  queryFn:  () => api.getProfile(userId),
});

// data is always ProfileData here — the component suspends until resolved
useFormState(profileSchema, { initialData: data });

import { parseState } from 'form-state';

const { data } = useSuspenseQuery({
  queryKey: ['profile', userId],
  queryFn: async () => {
    const apiData = await api.getProfile(userId);
    const result = parseState(profileSchema, apiData);

    if (result.success) {
      return result.data;
    } else {
      throw new Error(result.errors.getAll().join(' | '));
    }
  },
});

<ErrorBoundary fallback={<ErrorMessage />}>
  <Suspense fallback={<Skeleton />}>
    <ProfileForm userId={userId} />
  </Suspense>
</ErrorBoundary>

const { mutateAsync } = useMutation({
  mutationFn: (values: ProfileApiData) => api.updateProfile(userId, values),
});

const handleSubmit = formHandlers.handleSubmit(
  async (submitState: SubmitState<typeof profileSchema>) => {
    // Abort and display schema errors if client-side validation failed
    if (!submitState.valid) return submitState.errors;

    try {
      await mutateAsync(profileSchema.toObject(submitState.data));
      return true;                         // signals success to formStatus
    } catch (err) {
      // Returning an object surfaces it as a manual error in the form
      return { _serverError: err instanceof Error ? err.message : 'Save failed.' };
    }
  }
);

const handleSubmit = formHandlers.handleSubmit(
  async (submitState) => { /* ... */ },
  {
    resetDirty: true,
    onSuccess: () => {
      // Refetch fires in the background; dirty-field protection means the
      // fresh data fills only fields the user hasn't touched since the save.
      queryClient.invalidateQueries({ queryKey: ['profile', userId] });
    },
  }
);

// Form-level error — display it near the submit button or at the top
return { _serverError: 'The server is unavailable. Try again later.' };

// Field-level error returned from the server
return { email: 'This email is already registered.' };

// Read either with getManual() — schema errors use errors.name, errors.email etc.
<FormError error={formState.errors.getManual('_serverError')} />

npm install github:dstarosta/FormStateTools#v1.0.0

import { FormDock } from 'form-state-tools';

function AppForm() {
  const form = useFormState(schema);   // or useFormStateContext(schema)
  const { Form, formHandlers } = form;

  return (
    <>
      <Form action={formHandlers.handleSubmit(onSubmit)}>
        {/* ... */}
      </Form>

      <FormDock form={form} />
    </>
  );
}

// Start expanded, only capture console.error calls
<FormDock form={form} collapsed={false} captureErrors="console" />

// Suppress noisy third-party errors
<FormDock
  form={form}
  ignoreErrorPatterns={[
    /ResizeObserver loop/,
    'Non-Error promise rejection',
  ]}
/>

// Force-disable in dev for a specific story/test
<FormDock form={form} devMode={false} />