TanStack Form Patterns

Quick Guide: Use
useForm
with
defaultValues
and typed generics. Render fields with
form.Field
using the render-prop
children
pattern. Validation lives in the
validators
prop on both form and field level — use
onChange
,
onBlur
,
onSubmit
(sync) and their
Async
variants. Use
mode="array"
for dynamic field lists with
pushValue
/
removeValue
. Use
onChangeListenTo
for cross-field validation. For app-wide consistency, create a shared
useAppForm
via
createFormHook
. Always provide
defaultValues
— TanStack Form infers types from them.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type
, named constants)

(You MUST provide
defaultValues
to
useForm
— TanStack Form infers field types from them)

(You MUST use
form.Field
with the
children
render prop — TanStack Form does not use
register
or
Controller
)

(You MUST use the
validators
prop for validation — NOT inline
rules
or external resolver wrappers)

(You MUST handle
field.state.meta.errors
as an array — always
.map()
over errors)

(You MUST call
form.handleSubmit()
inside the form's
onSubmit
handler with
e.preventDefault()
)

</critical_requirements>

Auto-detection: TanStack Form, @tanstack/react-form, @tanstack/vue-form, @tanstack/solid-form, @tanstack/angular-form, @tanstack/lit-form, useForm from tanstack, form.Field, createFormHook, createFormHookContexts, useAppForm, fieldContext, formContext, handleSubmit tanstack, pushValue, removeValue, onChangeListenTo, field.handleChange, field.handleBlur, field.state, formDevtoolsPlugin

When to use:

Building type-safe forms where field types are inferred from
```
defaultValues
```
Managing complex validation with sync, async, and cross-field rules
Dynamic forms with add/remove field groups (array fields)
Multi-framework projects (React, Vue, Solid, Angular, Lit)
Projects already using the TanStack ecosystem

When NOT to use:

Single input without validation (use native state)
Server-only forms with server actions (use native form + action)
Read-only data display (not a form scenario)

Detailed Resources:

examples/core.md - Basic form, Field component, TypeScript, form submission
examples/validation.md - Sync/async validation, validator adapters, form-level validation
examples/arrays.md - Dynamic array fields with pushValue/removeValue
examples/composition.md - createFormHook, useAppForm, listeners, side effects
reference.md - API tables, validator events, decision frameworks

Philosophy

TanStack Form is headless and type-safe by design. It owns zero UI — you render every input yourself. The library provides form state, validation orchestration, and field management. Types flow from

defaultValues

through every field name, value, and error — no manual generics required (though you can provide them).

Core Principles:

Type inference from defaults -
```
defaultValues
```
defines the form shape; field names and values are fully typed
Headless - Zero UI opinions; works with any component library or native inputs
Validation-event-driven - Validators attach to specific events (
```
onChange
```
,
```
onBlur
```
,
```
onSubmit
```
) per field or per form
Framework-agnostic core - Same mental model across React, Vue, Solid, Angular, and Lit
Composition via factory -
```
createFormHook
```
shares field/form components across an app

</philosophy>

Core Patterns

Pattern 1: Basic useForm + form.Field

Every form starts with

useForm

and renders fields via

form.Field

. The

children

render prop receives the field API with

state

handleChange

, and

handleBlur

tsx

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

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

return (
  <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>
);

Key difference from other form libraries: No

register

, no

Controller

, no

ref

forwarding. You always use

field.handleChange

and

field.state.value

explicitly.

See examples/core.md for complete form with error display and accessibility.

Pattern 2: Field-Level Validation

Validators are functions on the

validators

prop. Sync validators return a string (error) or

undefined

(valid). Async validators use

onChangeAsync

onBlurAsync

onSubmitAsync

tsx

<form.Field
  name="age"
  validators={{
    onChange: ({ value }) => (value < 13 ? "Must be 13 or older" : undefined),
    onBlurAsync: async ({ value }) => {
      const exists = await checkAge(value);
      return exists ? undefined : "Age not valid on server";
    },
  }}
  children={(field) => (
    <div>
      <input
        type="number"
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.valueAsNumber)}
      />
      {field.state.meta.errors.map((err) => (
        <em key={err} role="alert">
          {err}
        </em>
      ))}
    </div>
  )}
/>

Sync-first gating: When both

onBlur

and

onBlurAsync

exist, the async validator only runs if the sync validator passes. Same for

onChange

onChangeAsync

See examples/validation.md for all validation patterns and adapter integration.

Pattern 3: Linked Fields (Cross-Field Validation)

Use

onChangeListenTo

to re-run a field's validator when another field changes. This solves the stale-validation problem (e.g., confirm password).

tsx

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

Why this matters: Without

onChangeListenTo

, changing the

password

field does not re-validate

confirm_password

. The error stays stale until the user interacts with the confirm field again.

See examples/validation.md Pattern 4 for a complete linked fields example.

Pattern 4: Array Fields

Use

mode="array"

form.Field

to get

pushValue

removeValue

swapValues

moveValue

, and

insertValue

for dynamic field groups.

tsx

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

Important:

pushValue

requires a complete object matching the array item shape. Partial objects will cause type errors.

See examples/arrays.md for a complete dynamic list form.

Pattern 5: Form-Level Validation

Validators on

useForm

apply to the entire form. Use

onSubmitAsync

for server-side validation that returns field-specific errors.

tsx

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

Return shape:

{ form?: string, fields: Record<string, string> }

— the

form

key is optional for form-level errors,

fields

maps field names to their error messages. Return

null

when valid.

See examples/validation.md Pattern 3 for complete form-level validation.

Pattern 6: createFormHook (App-Wide Composition)

Use

createFormHook

to share custom field components and form components across the app. This eliminates boilerplate and enforces consistency.

tsx

import { createFormHookContexts, createFormHook } from "@tanstack/react-form";

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

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

Usage:

useAppForm

accepts all

useForm

options. Registered

fieldComponents

and

formComponents

are available on the returned form instance:

form.AppField

for custom field components,

form.AppForm

for form-level components.

See examples/composition.md for the full factory setup and custom component patterns.

Pattern 7: Listeners (Side Effects)

Listeners react to field events and perform side effects like resetting related fields. Use the

listeners

prop on

form.Field

tsx

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

Available events:

onChange

onBlur

onMount

onSubmit

. Listeners are for side effects only — they do not return validation errors.

See examples/composition.md Pattern 3 for a complete country/province cascade.

Pattern 8: form.Subscribe for Reactive UI

Use

form.Subscribe

to reactively render UI based on form state without re-rendering the entire form. Takes a

selector

to pick specific state.

tsx

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

Why this matters: Without

form.Subscribe

, reading

form.state

directly causes the parent component to re-render on every state change. The selector narrows the subscription.

</patterns>

<red_flags>

RED FLAGS

High Priority Issues:

Using
```
register
```
or
```
Controller
```
patterns — TanStack Form uses
```
form.Field
```
with
```
children
```
render prop, not register/Controller
Missing
```
defaultValues
```
in
```
useForm
```
— types cannot be inferred, fields start as
```
undefined
```
Calling
```
form.handleSubmit()
```
without
```
e.preventDefault()
```
— causes page reload
Reading
```
form.state
```
directly in the component body — causes full re-render on every change; use
```
form.Subscribe
```
or
```
useStore
```

Medium Priority Issues:

Using
```
onChange
```
validator for expensive checks — use
```
onChangeAsync
```
with debounce or
```
onBlurAsync
```
instead
Providing partial objects to
```
pushValue
```
in array fields — must provide complete objects matching the array item type
Not using
```
onChangeListenTo
```
for cross-field validation — related field errors go stale
Wrapping
```
form.handleSubmit()
```
in another async function without error handling —
```
handleSubmit
```
does not catch errors thrown in
```
onSubmit
```

Gotchas & Edge Cases:

```
field.state.meta.errors
```
is always an array — never compare with
```
===
```
, always
```
.map()
```
or
```
.length
```
Sync validators gate async validators — if
```
onChange
```
fails,
```
onChangeAsync
```
does not run
Form-level
```
onSubmitAsync
```
validator returns
```
{ fields: { fieldName: "error" } }
```
— not the same shape as field-level validators

field.state.meta.isTouched

only becomes

true

after

handleBlur

fires — not on first

handleChange

Array field access uses bracket notation:
```
name={
```
items[${i}].name
```
}
```
— not dot notation like
```
items.${i}.name
```
```
form.Subscribe
```
uses a
```
selector
```
prop to pick state — passing no selector subscribes to everything

createFormHook

components are available as

form.AppField

and

form.AppForm

— not on

form.Field

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md