TanStack Form Patterns

Quick Guide: useForm takes defaultValues, and every field name, value type and the submit payload are inferred from that object. Fields render through form.Field with a children render prop that supplies field.state.value, field.handleChange and field.handleBlur. Validation lives in the validators prop — keyed by event (onChange, onBlur, onSubmit) with an Async variant of each, on the field or on the form. mode="array" unlocks pushValue/removeValue, onChangeListenTo re-runs a validator when another field changes, and form.Subscribe narrows which state changes re-render what.

Detailed Resources:

• examples/core.md — a form end to end: fields, typing, submission, reset
• examples/validation.md — sync, async and cross-field validators; schema objects in validators
• examples/arrays.md — dynamic field groups with mode="array"
• examples/composition.md — createFormHook, useAppForm, listeners
• reference.md — validator events, field and form state tables, API methods, framework packages

---

Which path applies

• A single form — useForm plus form.Field render props, nothing else to set up. Follow examples/core.md.
• Forms across an app that should behave alike — createFormHook registers shared field and form components once, and useAppForm replaces useForm at each call site. Follow examples/composition.md.
• A framework other than React — the form core is shared and only the package and the field binding differ; reference.md's Framework Packages table names both for each.

---

<critical_requirements>

Before writing TanStack Form code

Give useForm a defaultValues entry for every field. Field names, value types and the submit payload are all inferred from that object, so a field missing from it is a field the types do not know about.

Render every field through form.Field and its children render prop. The render prop receives the value and the handlers explicitly — this library has no field-registration helper and does no ref forwarding, so an input wired any other way never joins the form.

Put validation in the validators prop, keyed by the event that should run it. onChange, onBlur and onSubmit each have an Async counterpart, and the same prop exists on the field and on the form.

Read field.state.meta.errors as an array. It holds every current error for the field, so .map() over it or check .length; compared against a string it is always unequal.

Call e.preventDefault() in the form's onSubmit before form.handleSubmit(). The library does not intercept the native submit, so without it the browser navigates away mid-submission.

</critical_requirements>

---

Auto-detection: @tanstack/react-form, @tanstack/vue-form, @tanstack/solid-form, @tanstack/angular-form, @tanstack/lit-form, @tanstack/form-core, form.Field, form.Subscribe, createFormHook, createFormHookContexts, useAppForm, withForm, fieldContext, formContext, field.handleChange, field.handleBlur, field.state.meta, pushValue, removeValue, swapValues, onChangeListenTo, onBlurListenTo, setErrorMap, formDevtoolsPlugin

Applies to:

• Form state, validation timing and submission
• Cross-field rules, where one field's validity depends on another's value
• Dynamic lists of field groups that add, remove and reorder
• Sharing field and form components across an app through the factory
• Forms in Vue, Solid, Angular or Lit as well as React

Handled elsewhere:

• Authoring the validation schema — a validator accepts any Standard Schema object, and how that schema states its rules is settled by whatever owns it.
• Rendering and styling the inputs — this library owns no UI; the render prop hands over the value and the handlers, and the markup is yours.
• Where the initial values came from — defaultValues is a plain object, and the form fetches nothing.

---

<philosophy>

The form is headless and its types run on inference. defaultValues is the schema of record: field names autocomplete from it, field.state.value is typed by it, and the onSubmit payload matches it — without a generic parameter, and without a second type declaration that could drift.

Validation is bound to events rather than to a mode. Each validator declares when it runs, at the level it belongs to, so a cheap format check can sit on onChange while the expensive uniqueness check waits for onBlurAsync on the same field.

State is read by subscription. form.Subscribe and useStore take a selector and re-render only when what the selector returns changes, so reading form.state directly in a component body opts out of the whole design.

</philosophy>

---

<patterns>

Core patterns

Pattern 1: useForm and form.Field

The render prop is the whole field API — value in, handlers out, nothing implicit.

const form = useForm({
  defaultValues: { name: "", email: "" },
  onSubmit: async ({ value }) => {
    await submitToApi(value);
  },
});

<form
  onSubmit={(e) => {
    e.preventDefault();
    form.handleSubmit();
  }}
>
  <form.Field
    name="email"
    children={(field) => (
      <input
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
      />
    )}
  />
</form>;

onBlur={field.handleBlur} is what marks the field touched — omit it and isTouched stays false and any onBlur validator never runs.

Full code: examples/core.md

---

Pattern 2: Field-level validators

A sync validator returns a message string, or undefined when the value passes.

<form.Field
  name="age"
  validators={{
    onChange: ({ value }) => (value < 13 ? "Must be 13 or older" : undefined),
    onBlurAsync: async ({ value }) => {
      const ok = await checkAge(value);
      return ok ? undefined : "Age not valid on server";
    },
  }}
  children={(field) => (/* ... */)}
/>

Sync gates async: when onBlur and onBlurAsync are both present, the async one runs only after the sync one passes — so a network call never fires on a value already known to be invalid.

Full code: examples/validation.md

---

Pattern 3: Linked fields

onChangeListenTo names the fields whose changes should re-run this field's validators.

<form.Field
  name="confirm_password"
  validators={{
    onChangeListenTo: ["password"],
    onChange: ({ value, fieldApi }) =>
      value !== fieldApi.form.getFieldValue("password")
        ? "Passwords do not match"
        : undefined,
  }}
  children={(field) => (/* ... */)}
/>

Without it, editing password leaves the error on confirm_password showing the verdict from the old comparison until the user touches the confirm field again.

Full code: examples/validation.md

---

Pattern 4: Array fields

mode="array" gives the field pushValue, removeValue, insertValue, swapValues and moveValue. Nested fields address items by index.

<form.Field
  name="hobbies"
  mode="array"
  children={(hobbies) => (
    <div>
      {hobbies.state.value.map((_, i) => (
        <form.Field
          key={i}
          name={`hobbies[${i}].name`}
          children={(field) => (
            <input
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
            />
          )}
        />
      ))}
      <button type="button" onClick={() => hobbies.pushValue({ name: "" })}>
        Add hobby
      </button>
    </div>
  )}
/>

Full code: examples/arrays.md

---

Pattern 5: Form-level validators

Validators on useForm see every value at once, which is where server-side validation belongs because it can attribute errors back to individual fields.

const form = useForm({
  defaultValues: { username: "", age: 0 },
  validators: {
    onSubmitAsync: async ({ value }) => {
      const errors = await validateOnServer(value);
      if (!errors) return null;
      return {
        form: "Submission failed",
        fields: { username: errors.username, age: errors.age },
      };
    },
  },
});

The return shape is { form?: string, fields: Record<string, string> }, and null means valid. This differs from a field validator, which returns a bare string.

Full code: examples/validation.md

---

Pattern 6: createFormHook

The factory registers field and form components once, so each form reaches them as form.AppField and form.AppForm instead of repeating the render-prop markup.

export const { fieldContext, formContext, useFieldContext } =
  createFormHookContexts();

export const { useAppForm, withForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { TextField, SelectField },
  formComponents: { SubmitButton },
});

useAppForm accepts everything useForm does.

Full code: examples/composition.md

---

Pattern 7: Listeners

Listeners react to a field event and cause an effect. They return nothing — a validator is what returns errors.

<form.Field
  name="country"
  listeners={{
    onChange: () => form.setFieldValue("province", ""),
  }}
  children={(field) => (/* ... */)}
/>

Available events: onChange, onBlur, onMount, onSubmit.

Full code: examples/composition.md

---

Pattern 8: form.Subscribe

The selector decides what re-renders. Narrow it to the state actually rendered.

<form.Subscribe
  selector={(state) => [state.canSubmit, state.isSubmitting] as const}
  children={([canSubmit, isSubmitting]) => (
    <button type="submit" disabled={!canSubmit || isSubmitting}>
      {isSubmitting ? "Submitting..." : "Submit"}
    </button>
  )}
/>

Full code: examples/core.md

</patterns>

---

<red_flags>

Red flags

Breaks at runtime:

• form.handleSubmit() without e.preventDefault() — the browser submits the form natively and the page reloads mid-submission.
• defaultValues missing a field — its field.state.value is undefined, the input mounts uncontrolled, and the field's type is unknown.
• field.state.meta.errors compared as a string — it is an array, so the comparison is always false and the message never renders. .map() over it.
• A partial object handed to pushValue — it does not match the array's element type, and the absent keys leave their inputs uncontrolled.
• An error thrown inside onSubmit — form.handleSubmit() does not catch it. Catch inside the callback and surface it with form.setErrorMap().
• Dot notation for an array item — the field path is items[0].name, and items.0.name addresses nothing.

Surprising behaviour:

• form.state read in a component body subscribes to every state change. form.Subscribe with a selector, or useStore(form.store, selector), narrows it.
• form.Subscribe with no selector subscribes to everything, which is the same cost.
• A sync validator failing stops its async counterpart from running at all — deliberate, and it means an async validator alone carries no cheap pre-check.
• A form-level validator returns { form?, fields } while a field validator returns a string — the field shape returned from the form level is ignored in silence.
• Components registered through createFormHook live on form.AppField and form.AppForm; form.Field still exists and still takes a plain render prop.

Worked before/after code for the most common of these is in reference.md.

</red_flags>