TanStack Form
Overview
TanStack Form is a headless form state manager, not a UI component library. You provide your own inputs and handle their events; TanStack Form manages validation, state, and submission logic.
When to use: Complex multi-step forms, reusable form patterns, dynamic field arrays, cross-field validation, async server validation, forms requiring fine-grained performance optimization.
When NOT to use: Simple forms with native HTML validation (use plain form elements), server-only validation (use Server Actions), purely static forms with no validation.
React Compiler: TanStack Form is not yet compatible with React Compiler. Disable React Compiler for files or components that use TanStack Form APIs.
Quick Reference
| Pattern |
API |
Key Points |
| Basic form |
useForm({ defaultValues, onSubmit }) |
Form instance with Field component |
| Field |
form.Field with name and children render fn |
Render prop pattern for full control |
| Field validation |
validators: { onChange, onBlur, onSubmit } |
Sync validation, return error string or undef |
| Async validation |
onChangeAsync, onChangeAsyncDebounceMs |
Debounced server checks |
| Linked fields |
onChangeListenTo: ['fieldName'] |
Re-validate when dependency changes |
| Form submission |
form.handleSubmit() |
Validates and calls onSubmit if valid |
| Form state |
form.state.values, isSubmitting, isValid |
Access form-level state |
| Field state |
field.state.value, meta.errors, meta.isTouched |
Access field-level state |
| Array fields |
mode="array", pushValue, removeValue |
Dynamic lists with helpers |
| Standard Schema |
Pass Zod/Valibot/ArkType/Yup schema directly |
Native support, no adapter needed |
| Form composition |
createFormHook({ fieldComponents }) |
Reusable fields with context |
| Break up large forms |
withForm({ defaultValues, render }) |
HOC for form sections with type safety |
| Reusable field groups |
withFieldGroup({ defaultValues, render }) |
Grouped fields with shared validation logic |
| Subscribe to state |
form.Subscribe with selector |
Efficient re-render control |
| Field error display |
meta.isTouched && meta.errors.length |
Show errors after user interaction |
| Form-level validation |
validators.onSubmit returning { fields } |
Set errors on specific fields from form level |
| Reset form |
form.reset() |
Reset to defaultValues |
Common Mistakes
| Mistake |
Correct Pattern |
Using e.target.value directly |
Use field.handleChange(value) for proper state management |
Missing onBlur={field.handleBlur} |
Always add for validation timing and touched state |
| Showing errors immediately |
Check field.state.meta.isTouched && errors.length |
| Not specifying debounce for async validation |
Set onChangeAsyncDebounceMs to avoid excessive server requests |
Using listeners for validation |
Use onChangeListenTo in validators for re-validation |
| Validating only on submit |
Add onChange or onBlur validators for better UX |
| Not handling form submission properly |
Prevent default and call form.handleSubmit() |
| Creating QueryClient-style instances |
Use useForm hook directly in components |
| Inline validator functions |
Extract to stable references or wrap in useCallback |
| Missing field names in array fields |
Use template syntax hobbies[${index}].name for nested fields |
| Not awaiting async validators |
Return Promise directly, Form handles awaiting |
Checking isValidating before submission |
Use canSubmit state selector instead |
Delegation
- Form pattern discovery: Use
Explore agent for finding existing form implementations
- Validation schema design: Use
Task agent for complex cross-field validation logic
- Code review: Delegate to
code-reviewer agent for form validation coverage
If the shadcn-ui skill is available, delegate component styling and composition to it. Otherwise, recommend: npx skills add oakoss/agent-skills --skill shadcn-ui
If the tanstack-query skill is available, delegate cache management and mutation patterns to it.
If the tanstack-start skill is available, delegate server functions and server-side form submission to it.
If the tanstack-router skill is available, delegate post-submission navigation and route patterns to it.
If the tanstack-devtools skill is available, delegate form state debugging to it.
References
- Basic patterns and form setup
- Field validation (sync, async, linked fields)
- Schema validation (Zod, Valibot, ArkType, Yup)
- Array fields and dynamic lists
- Form composition and reusable fields
- Advanced patterns (multi-step forms, file uploads)
- Server integration (mutations, cache coordination, server functions)
- React Aria integration (TextField, Select, Switch, Checkbox, RadioGroup)
- shadcn/ui integration (Field layout, Input, Select, Switch, Checkbox, RadioGroup)
1---2name: tanstack-form3description: TanStack Form v1 headless form state management for React. Covers field validation (sync/async, debouncing), form submission, array fields, linked fields, form composition patterns, and Standard Schema integration (Zod, Valibot, ArkType, Yup). Use when building forms with complex validation, implementing reusable form components, handling dynamic field lists, managing form state, or integrating validation libraries.4license: MIT5---6
7# TanStack Form
8
9## Overview
10
11TanStack Form is a **headless form state manager**, not a UI component library. You provide your own inputs and handle their events; TanStack Form manages validation, state, and submission logic.
12
13**When to use:** Complex multi-step forms, reusable form patterns, dynamic field arrays, cross-field validation, async server validation, forms requiring fine-grained performance optimization.
14
15**When NOT to use:** Simple forms with native HTML validation (use plain form elements), server-only validation (use Server Actions), purely static forms with no validation.
16
17**React Compiler:** TanStack Form is not yet compatible with React Compiler. Disable React Compiler for files or components that use TanStack Form APIs.
18
19## Quick Reference
20
21| Pattern | API | Key Points |
22| --------------------- | ---------------------------------------------------- | --------------------------------------------- |
23| Basic form | `useForm({ defaultValues, onSubmit })` | Form instance with Field component |
24| Field | `form.Field` with `name` and `children` render fn | Render prop pattern for full control |
25| Field validation | `validators: { onChange, onBlur, onSubmit }` | Sync validation, return error string or undef |
26| Async validation | `onChangeAsync`, `onChangeAsyncDebounceMs` | Debounced server checks |
27| Linked fields | `onChangeListenTo: ['fieldName']` | Re-validate when dependency changes |
28| Form submission | `form.handleSubmit()` | Validates and calls onSubmit if valid |
29| Form state | `form.state.values`, `isSubmitting`, `isValid` | Access form-level state |
30| Field state | `field.state.value`, `meta.errors`, `meta.isTouched` | Access field-level state |
31| Array fields | `mode="array"`, `pushValue`, `removeValue` | Dynamic lists with helpers |
32| Standard Schema | Pass Zod/Valibot/ArkType/Yup schema directly | Native support, no adapter needed |
33| Form composition | `createFormHook({ fieldComponents })` | Reusable fields with context |
34| Break up large forms | `withForm({ defaultValues, render })` | HOC for form sections with type safety |
35| Reusable field groups | `withFieldGroup({ defaultValues, render })` | Grouped fields with shared validation logic |
36| Subscribe to state | `form.Subscribe` with `selector` | Efficient re-render control |
37| Field error display | `meta.isTouched && meta.errors.length` | Show errors after user interaction |
38| Form-level validation | `validators.onSubmit` returning `{ fields }` | Set errors on specific fields from form level |
39| Reset form | `form.reset()` | Reset to defaultValues |
40
41## Common Mistakes
42
43| Mistake | Correct Pattern |
44| -------------------------------------------- | ---------------------------------------------------------------- |
45| Using `e.target.value` directly | Use `field.handleChange(value)` for proper state management |
46| Missing `onBlur={field.handleBlur}` | Always add for validation timing and touched state |
47| Showing errors immediately | Check `field.state.meta.isTouched && errors.length` |
48| Not specifying debounce for async validation | Set `onChangeAsyncDebounceMs` to avoid excessive server requests |
49| Using `listeners` for validation | Use `onChangeListenTo` in validators for re-validation |
50| Validating only on submit | Add `onChange` or `onBlur` validators for better UX |
51| Not handling form submission properly | Prevent default and call `form.handleSubmit()` |
52| Creating QueryClient-style instances | Use `useForm` hook directly in components |
53| Inline validator functions | Extract to stable references or wrap in useCallback |
54| Missing field names in array fields | Use template syntax `hobbies[${index}].name` for nested fields |
55| Not awaiting async validators | Return Promise directly, Form handles awaiting |
56| Checking `isValidating` before submission | Use `canSubmit` state selector instead |
57
58## Delegation
59
60- **Form pattern discovery**: Use `Explore` agent for finding existing form implementations
61- **Validation schema design**: Use `Task` agent for complex cross-field validation logic
62- **Code review**: Delegate to `code-reviewer` agent for form validation coverage
63
64> If the `shadcn-ui` skill is available, delegate component styling and composition to it. Otherwise, recommend: `npx skills add oakoss/agent-skills --skill shadcn-ui`
65>
66> If the `tanstack-query` skill is available, delegate cache management and mutation patterns to it.
67> If the `tanstack-start` skill is available, delegate server functions and server-side form submission to it.
68> If the `tanstack-router` skill is available, delegate post-submission navigation and route patterns to it.
69> If the `tanstack-devtools` skill is available, delegate form state debugging to it.
70
71## References
72
73- [Basic patterns and form setup](references/basic-patterns.md)
74- [Field validation (sync, async, linked fields)](references/validation.md)
75- [Schema validation (Zod, Valibot, ArkType, Yup)](references/schema-validation.md)
76- [Array fields and dynamic lists](references/array-fields.md)
77- [Form composition and reusable fields](references/form-composition.md)
78- [Advanced patterns (multi-step forms, file uploads)](references/advanced-patterns.md)
79- [Server integration (mutations, cache coordination, server functions)](references/server-integration.md)
80- [React Aria integration (TextField, Select, Switch, Checkbox, RadioGroup)](references/react-aria-integration.md)
81- [shadcn/ui integration (Field layout, Input, Select, Switch, Checkbox, RadioGroup)](references/shadcn-integration.md)
oakoss