Overview

TanStack Form is a headless form library with deep TypeScript integration. It provides field-level and form-level validation (sync/async), array fields, linked/dependent fields, fine-grained reactivity, and schema validation adapter support (Zod, Valibot, Yup).

Package: @tanstack/react-form Adapters: @tanstack/zod-form-adapter, @tanstack/valibot-form-adapter Status: Stable (v1)

Installation

npm install @tanstack/react-form
# Optional schema adapters:
npm install @tanstack/zod-form-adapter zod
npm install @tanstack/valibot-form-adapter valibot

Core: useForm

import { useForm } from "@tanstack/react-form";

function MyForm() {
  const form = useForm({
    defaultValues: {
      firstName: "",
      lastName: "",
      email: "",
      age: 0,
    },
    onSubmit: async ({ value }) => {
      // value is fully typed
      await submitToServer(value);
    },
    onSubmitInvalid: ({ value, formApi }) => {
      console.log("Validation failed:", formApi.state.errors);
    },
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.stopPropagation();
        form.handleSubmit();
      }}
    >
      {/* Fields */}
      <form.Subscribe
        selector={(state) => ({
          canSubmit: state.canSubmit,
          isSubmitting: state.isSubmitting,
        })}
        children={({ canSubmit, isSubmitting }) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? "Submitting..." : "Submit"}
          </button>
        )}
      />
    </form>
  );
}

Fields (form.Field)

<form.Field
  name="firstName"
  validators={{
    onChange: ({ value }) =>
      value.length < 3 ? 'Must be at least 3 characters' : undefined,
  }}
  children={(field) => (
    <div>
      <label htmlFor={field.name}>First Name</label>
      <input
        id={field.name}
        name={field.name}
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
      />
      {field.state.meta.isTouched && field.state.meta.errors.length > 0 && (
        <em>{field.state.meta.errors.join(', ')}</em>
      )}
    </div>
  )}
/>

<!-- Nested fields use dot notation -->
<form.Field name="address.city">
  {(field) => (
    <input
      value={field.state.value}
      onChange={(e) => field.handleChange(e.target.value)}
      onBlur={field.handleBlur}
    />
  )}
</form.Field>

Validation

Validation Timing

Cause	When
`onChange`	After every value change
`onBlur`	When field loses focus
`onSubmit`	During submission
`onMount`	When field mounts

Synchronous Validation

<form.Field
  name="age"
  validators={{
    onChange: ({ value }) => {
      if (value < 18) return "Must be 18 or older";
      return undefined; // undefined = valid
    },
    onBlur: ({ value }) => {
      if (!value) return "Required";
      return undefined;
    },
  }}
/>

Asynchronous Validation

<form.Field
  name="username"
  asyncDebounceMs={500}
  validators={{
    onChangeAsync: async ({ value }) => {
      const res = await fetch(`/api/check-username?q=${value}`);
      const { available } = await res.json();
      if (!available) return "Username taken";
      return undefined;
    },
  }}
>
  {(field) => (
    <>
      <input
        value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)}
      />
      {field.state.meta.isValidating && <span>Checking...</span>}
    </>
  )}
</form.Field>

Schema Validation (Zod)

import { zodValidator } from '@tanstack/zod-form-adapter'
import { z } from 'zod'

const form = useForm({
  defaultValues: { email: '', age: 0 },
  validatorAdapter: zodValidator(),
  onSubmit: async ({ value }) => { /* ... */ },
})

<form.Field
  name="email"
  validators={{
    onChange: z.string().email('Invalid email'),
    onBlur: z.string().min(1, 'Required'),
  }}
/>

<form.Field
  name="age"
  validators={{
    onChange: z.number().min(18, 'Must be 18+'),
  }}
/>

Form-Level Validation

const form = useForm({
  defaultValues: { password: "", confirmPassword: "" },
  validators: {
    onChange: ({ value }) => {
      if (value.password !== value.confirmPassword) {
        return "Passwords do not match";
      }
      return undefined;
    },
  },
});

Linked/Dependent Fields

<form.Field
  name="confirmPassword"
  validators={{
    onChangeListenTo: ["password"], // Re-validate when password changes
    onChange: ({ value, fieldApi }) => {
      const password = fieldApi.form.getFieldValue("password");
      if (value !== password) return "Passwords do not match";
      return undefined;
    },
  }}
/>

Array Fields

<form.Field name="people" mode="array">
  {(field) => (
    <div>
      {field.state.value.map((_, index) => (
        <div key={index}>
          <form.Field name={`people[${index}].name`}>
            {(subField) => (
              <input
                value={subField.state.value}
                onChange={(e) => subField.handleChange(e.target.value)}
              />
            )}
          </form.Field>
          <button type="button" onClick={() => field.removeValue(index)}>
            Remove
          </button>
        </div>
      ))}
      <button
        type="button"
        onClick={() => field.pushValue({ name: "", age: 0 })}
      >
        Add Person
      </button>
    </div>
  )}
</form.Field>

Array Methods

field.pushValue(item); // Add to end
field.insertValue(index, item); // Insert at index
field.replaceValue(index, item); // Replace at index
field.removeValue(index); // Remove at index
field.swapValues(indexA, indexB); // Swap positions
field.moveValue(from, to); // Move position

Listeners (Side Effects)

<form.Field
  name="country"
  listeners={{
    onChange: ({ value }) => {
      // Side effect: reset dependent fields
      form.setFieldValue("state", "");
      form.setFieldValue("postalCode", "");
    },
  }}
/>

Reactivity (form.Subscribe & useStore)

// Render-prop subscription (fine-grained)
<form.Subscribe
  selector={(state) => ({ canSubmit: state.canSubmit, isDirty: state.isDirty })}
  children={({ canSubmit, isDirty }) => (
    <div>
      {isDirty && <span>Unsaved changes</span>}
      <button disabled={!canSubmit}>Save</button>
    </div>
  )}
/>;

// Hook-based subscription
function FormStatus() {
  const isValid = form.useStore((s) => s.isValid);
  return isValid ? null : <p>Fix errors</p>;
}

Form State

interface FormState {
  values: TFormData;
  errors: ValidationError[];
  errorMap: Record<string, ValidationError>;
  isFormValid: boolean;
  isFieldsValid: boolean;
  isValid: boolean; // isFormValid && isFieldsValid
  isTouched: boolean;
  isPristine: boolean;
  isDirty: boolean;
  isSubmitting: boolean;
  isSubmitted: boolean;
  isSubmitSuccessful: boolean;
  submissionAttempts: number;
  canSubmit: boolean; // isValid && !isSubmitting
}

Field State

interface FieldState<TData> {
  value: TData;
  meta: {
    isTouched: boolean;
    isDirty: boolean;
    isPristine: boolean;
    isValidating: boolean;
    errors: ValidationError[];
    errorMap: Record<ValidationCause, ValidationError>;
  };
}

FormApi Methods

form.handleSubmit();
form.reset();
form.getFieldValue(field);
form.setFieldValue(field, value);
form.getFieldMeta(field);
form.setFieldMeta(field, updater);
form.validateAllFields(cause);
form.validateField(field, cause);
form.deleteField(field);

Shared Form Options (formOptions)

import { formOptions } from "@tanstack/react-form";

const sharedOpts = formOptions({
  defaultValues: { firstName: "", lastName: "" },
});

// Reuse across components
const form = useForm({
  ...sharedOpts,
  onSubmit: async ({ value }) => {
    /* ... */
  },
});

Server-Side Validation

// TanStack Start / Next.js server action
import { ServerValidateError } from "@tanstack/react-form/nextjs";

export async function validateForm(data: FormData) {
  const email = data.get("email") as string;
  if (await checkEmailExists(email)) {
    throw new ServerValidateError({
      form: "Submission failed",
      fields: { email: "Email already registered" },
    });
  }
}

TypeScript Integration

// Type-safe field paths with DeepKeys
interface UserForm {
  name: string
  address: { street: string; city: string }
  tags: string[]
  contacts: Array<{ name: string; phone: string }>
}

// TypeScript auto-completes all valid paths:
// 'name', 'address', 'address.street', 'address.city', 'tags', 'contacts'
<form.Field name="address.city" />     // OK
<form.Field name="nonexistent" />       // Type Error!

Best Practices

Always call e.preventDefault() and e.stopPropagation() on form submit
Always attach onBlur={field.handleBlur} for blur validation and isTouched tracking
Use mode="array" for array fields to get array methods
Return undefined (not null/false) for valid validators
Use asyncDebounceMs for async validators to prevent API spam
Check isTouched before showing errors for better UX
Use form.Subscribe with selectors to minimize re-renders
Use formOptions for shared configuration across components
Use schema validators (Zod/Valibot) for complex validation rules
Use onChangeListenTo for cross-field validation dependencies

Common Pitfalls

Forgetting e.preventDefault() on form submit (causes page reload)
Not attaching onBlur to inputs (breaks blur validation and isTouched)
Returning null or false instead of undefined for valid fields
Using mode="array" incorrectly (only needed on the array field itself, not sub-fields)
Subscribing to entire form state instead of using selectors (unnecessary re-renders)
Not using asyncDebounceMs with async validators (fires on every keystroke)

tanstack-form