TanStack Form v2

For initial setup see setup.md. For withForm, withFieldGroup, and extendForm see composition.md. For array fields see arrays.md.

Rules

1. Define form shape with formOptions() — share it into useAppForm and any withForm sub-components via spread
2. Schemas live in the form file (or a sibling schema.ts), never inside field components
3. Field components are dumb UI wrappers — they own no schema knowledge and no defaults
4. onSubmit only calls mutation.mutate — side effects go in useMutation callbacks
5. Wrap form.SubmitButton in form.AppForm
6. Zod error messages: prefix with "i18n:" if project uses i18n (check package.json for react-i18next)
7. Forms with 3+ distinct sections → split with withForm HOC
8. Field groups reused across multiple forms → withFieldGroup HOC
9. render in withForm/withFieldGroup must be a named function, not an arrow function (ESLint hooks rule)

Form Shape

formOptions() is the canonical primitive. Define it once; spread into useAppForm (and into withForm sub-components — see composition.md).

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

const schema = z.object({
  name: z.string().min(1, "i18n:validation.required"),
  email: z.string().email("i18n:validation.email"),
});

const opts = formOptions({
  defaultValues: { name: "", email: "" },
});

// ---

const mutation = useMutation({
  mutationFn: myServerFn,
  onSuccess: () => { /* redirect, invalidate */ },
});

const form = useAppForm({
  ...opts,
  validators: { onSubmit: schema },
  onSubmit: ({ value }) => mutation.mutate({ data: value }),
});

<form onSubmit={(e) => { e.preventDefault(); e.stopPropagation(); form.handleSubmit(); }}>
  <form.AppField name="name">{(field) => <field.InputField label="Name" />}</form.AppField>
  <form.AppField name="email">{(field) => <field.InputField label="Email" type="email" />}</form.AppField>
  {mutation.isError && <p className="text-sm text-destructive">Something went wrong.</p>}
  <form.AppForm>
    <form.SubmitButton isLoading={mutation.isPending}>Submit</form.SubmitButton>
  </form.AppForm>
</form>

Adding a Field

Field components are pure UI. They read from context, render the input, show errors. They know nothing about schemas or defaults.

1. Create <name>-field.tsx — import useFieldContext from form-context, not form-setup

import { useFieldContext } from "../form-context";
import { useFormatError } from "src/lib/use-format-error";

export function MyField({ label, ...props }: { label: string } & Omit<ComponentProps<typeof UiComp>, "value" | "onChange" | "onBlur">) {
  const field = useFieldContext<string>();
  const formatError = useFormatError();
  const error = field.state.meta.isValid ? undefined : formatError(field.state.meta.errors);
  return (
    <FormField label={label} error={error}>
      <UiComp {...props} id={field.name} value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)} onBlur={field.handleBlur} aria-invalid={!!error || undefined} />
    </FormField>
  );
}

2. Register in form-setup.ts fieldComponents

3. Use at call site — all UI props go here, never inside the field component

<form.AppField name="x">{(field) => <field.MyField label="X" placeholder="…" />}</form.AppField>

Common Mistakes