TanStack Form
Knowledge base from the official TanStack Form documentation — a headless, type-safe form state management library for React, Vue, Angular, Solid, Lit, and Svelte. Use when building or debugging forms with useForm/Field, wiring validation (sync/async/schema-based), managing array fields, composing reusable form components, integrating with a UI library, handling SSR form actions (TanStack Start/Next.js/Remix), or comparing against React Hook Form.
TanStack Form
Package: @tanstack/react-form (+ per-framework adapters) | Chapters: 29 (6 Overview/Setup + 18 React Guides + 4 API Reference + 1 Framework Adapters) | Generated: 2026-08-25
How to Use This Skill
- Without arguments — load Core Patterns below for the mental model shared across every framework adapter
- With a concept name — ask about
array fields,validation,form composition,SSR,useForm, etc.; I find and read the matching chapter - With a chapter — ask for
ch020; I load that specific chapter - Browse — ask "what chapters do you have?" to see the full index
When you ask about a topic not covered in Core Patterns below, I will read the relevant chapter file before answering.
Core Patterns & Conventions
Headless, subscription-based, not auto-reactive. No re-render happens unless a component explicitly subscribes to a slice of form state via useSelector(form.store, selector) or form.Subscribe — omitting the selector re-subscribes to everything and defeats the point.
defaultValues is the type-inference source, not just an initial value. Field names (DeepKeys) and value types (DeepValue) are both inferred from it — you should never write a field-name generic by hand.
Validators are timing + scope, fully orthogonal. Pick timing (onMount/onChange/onBlur/onSubmit, each with an async variant) and scope (field-level vs form-level) independently; a Standard Schema (Zod/Valibot/ArkType) can be passed directly as a validator with no adapter.
Validators and listeners are different tools. A validator answers "is this valid?"; a listener runs a side effect ("reset this other field," "auto-save"). Don't smuggle side effects into a validator that happens to return undefined.
Cross-field dependencies need onChangeListenTo/onChangeListenTo, not just a form-level validator. A field's own validator only re-runs on that field's changes by default — "confirm password" won't re-check itself when "password" changes unless it explicitly listens.
Array fields are mutated through methods, never by reassigning the array. pushValue/removeValue/insertValue/replaceValue/swapValues/moveValue exist on both FieldApi and FormApi — reassigning field.state.value directly breaks change detection.
createFormHook is the intended way to use this library at scale, not raw useForm/form.Field in every component — pre-bind your own field/form components once, then every form gets typed, pre-styled fields via useAppForm/form.AppField.
SSR (TanStack Start/Next.js/Remix) is createServerValidate on the server + mergeForm/useTransform on the client, reconciling server-validated state into the client form rather than replacing it — install the framework-specific package, don't hand-roll the wiring.
Chapter Index
Overview & Setup
| # | Title | Key Concepts |
|---|---|---|
| ch001 | Overview | headless architecture, subscription model, multi-stage validation |
| ch002 | Installation | per-framework packages, meta-framework/devtools add-ons |
| ch003 | Philosophy | unified API, controlled components, type inference over generics |
| ch004 | Comparison | vs. React Hook Form, Formik, Redux Form, Final Form |
| ch005 | TypeScript | strict mode, version pinning, non-semver type changes |
| ch006 | React Quick Start | useForm + form.Field minimal shape |
React Guides
| # | Title | Key Concepts |
|---|---|---|
| ch007 | Basic Concepts | form instance, field instance, field state, subscriptions |
| ch008 | Form Validation | timing, sync/async, Standard Schema integration |
| ch009 | Dynamic Validation | onDynamic, revalidateLogic, pre/post-submit modes |
| ch010 | Async Initial Values | loading gate, TanStack Query pairing |
| ch011 | Arrays | mode="array", pushValue/removeValue/insertValue/swapValues/moveValue |
| ch012 | Form Groups | FormGroup, multi-step wizards |
| ch013 | Linked Fields | onChangeListenTo/onBlurListenTo, cross-field validation |
| ch014 | Reactivity | useSelector, form.Subscribe, selector discipline |
| ch015 | Listeners | onChange/onBlur/onMount side effects, debouncing |
| ch016 | Custom Errors | truthy-value error contract, structured error objects |
| ch017 | Submission Handling | handleSubmit, onSubmitMeta, schema transforms |
| ch018 | UI Libraries Integration | render-prop wiring, MUI/shadcn/Mantine/Chakra |
| ch019 | Focus Management | onSubmitInvalid, aria-invalid, manual focus |
| ch020 | Form Composition | createFormHook, withForm, withFieldGroup |
| ch021 | React Native | works out-of-the-box, TextInput binding |
| ch022 | SSR & Meta-Frameworks | TanStack Start, Next.js Server Actions, Remix |
| ch023 | Debugging | uncontrolled-input warning, unknown value type, deep type errors |
| ch024 | Devtools | TanStackDevtools, formDevtoolsPlugin |
API Reference
| # | Title | Key Concepts |
|---|---|---|
| ch025 | React API Reference | useForm, useField, Field, FieldComponent, UseField |
| ch026 | Field & Form API Classes | FormApi/FieldApi methods, array mutators |
| ch027 | Options & Validators Types | FormOptions, FieldOptions, *Validators, formOptions, mergeForm |
| ch028 | Utility & State Types | DeepKeys/DeepValue, BaseFormState/DerivedFormState, Updater, ValidationError |
Framework Adapters
| # | Title | Key Concepts |
|---|---|---|
| ch029 | Framework Adapters | Preact/Vue/Solid/Svelte/Angular/Lit comparison table |
Topic Index
- Array fields → ch011, ch026
- Async validation → ch008, ch010
- Composition (createFormHook) → ch020
- Cross-field validation → ch013
- Debugging → ch023
- Devtools → ch024
- Dynamic validation → ch009
- Focus management → ch019
- Framework comparison (Vue/Solid/Angular/Lit/Svelte) → ch029
- Listeners (side effects) → ch015
- React Hook Form comparison → ch004
- React Native → ch021
- Reactivity / subscriptions → ch007, ch014
- Schema validation (Zod/Valibot/Standard Schema) → ch008
- SSR / server actions → ch022, ch027 (mergeForm)
- Submission → ch017
- TypeScript → ch005, ch028
- UI library integration → ch018
Supporting Files
- glossary.md — key terms with definitions
- patterns.md — common implementation patterns and trade-offs
- cheatsheet.md — decision rules and API quick-reference tables
Scope & Limits
This skill covers the official TanStack Form documentation as fetched 2026-08-25 (https://tanstack.com/form/latest/llms.txt), prioritizing the React adapter (@tanstack/react-form) in depth — the stack this skill library targets. Vue, Angular, Solid, Lit, Svelte, and Preact guides/examples/reference pages exist in the source but were not individually fetched; ch029 summarizes their form-creation call and field-binding idiom from each framework's Quick Start page only. For framework-specific depth beyond ch029, fetch that framework's docs pages directly from the llms.txt index.
There is no aggregated llms-full.txt for this library (unlike most other skills in this library) — content was synthesized from ~40 individually fetched Markdown pages via WebFetch, each summarized in this skill's own words, never reproduced verbatim.
Related skills: react-hook-form-docs — the dominant React-only alternative (see ch004 for the comparison). tanstack-query-docs — the common pairing for async-loaded form data (ch010). zod-docs/typescript-docs — Standard Schema validation (ch008) and the type-inference model (ch005, ch028) this library leans on heavily.