tanstack-form

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

TanStack Form 是一个无头表单状态管理器，而非UI组件库。你需要自行提供输入组件并处理它们的事件；TanStack Form 负责管理验证、状态和提交逻辑。

适用场景： 复杂的多步骤表单、可复用表单模式、动态字段数组、跨字段验证、异步服务器验证、需要细粒度性能优化的表单。

不适用场景： 仅使用原生HTML验证的简单表单（直接使用普通表单元素即可）、仅服务端验证的表单（使用Server Actions）、无验证的纯静态表单。

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
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

模式	API	核心要点
基础表单	`useForm({ defaultValues, onSubmit })`	带有Field组件的表单实例
字段	`form.Field` 配合 `name` 和 `children` 渲染函数	渲染属性模式，完全掌控组件
字段验证	`validators: { onChange, onBlur, onSubmit }`	同步验证，返回错误字符串或undefined
异步验证	`onChangeAsync` , `onChangeAsyncDebounceMs`	防抖的服务器校验
关联字段	`onChangeListenTo: ['fieldName']`	依赖字段变化时重新验证
表单提交	`form.handleSubmit()`	验证通过后调用onSubmit
表单状态	`form.state.values` , `isSubmitting` , `isValid`	访问表单级状态
字段状态	`field.state.value` , `meta.errors` , `meta.isTouched`	访问字段级状态
数组字段	`mode="array"` , `pushValue` , `removeValue`	带辅助方法的动态列表
标准Schema	直接传入Zod/Valibot/ArkType/Yup schema	原生支持，无需适配器
表单组合	`createFormHook({ fieldComponents })`	带上下文的可复用字段
状态订阅	`form.Subscribe` 配合 `selector`	高效控制重渲染
字段错误显示	`meta.isTouched && meta.errors.length`	用户交互后再显示错误
表单级验证	`validators.onSubmit` 返回 `{ fields }`	从表单层面为特定字段设置错误
重置表单	`form.reset()`	重置为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

错误	正确做法
直接使用 `e.target.value`	使用 `field.handleChange(value)` 进行正确的状态管理
遗漏 `onBlur={field.handleBlur}`	务必添加以控制验证时机和已触碰状态
立即显示错误	检查 `field.state.meta.isTouched && errors.length`
未为异步验证设置防抖	设置 `onChangeAsyncDebounceMs` 以避免过多服务器请求
使用 `listeners` 进行验证	在验证器中使用 `onChangeListenTo` 触发重新验证
仅在提交时验证	添加 `onChange` 或 `onBlur` 验证器以提升用户体验
未正确处理表单提交	阻止默认行为并调用 `form.handleSubmit()`
创建QueryClient风格的实例	在组件中直接使用 `useForm` 钩子
内联验证器函数	提取为稳定引用或用useCallback包裹
数组字段中缺失字段名称	对嵌套字段使用模板语法 `hobbies[${index}].name`
未等待异步验证器完成	直接返回Promise，Form会自动处理等待
提交前检查 `isValidating` 状态	改用 `canSubmit` 状态选择器替代

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
react-aria
skill is available, delegate accessible form component patterns to it. Otherwise, recommend:
npx skills add oakoss/agent-skills --skill react-aria

表单模式探索：使用
```
Explore
```
工具查找现有表单实现
验证Schema设计：使用
```
Task
```
工具处理复杂的跨字段验证逻辑
代码审查：委托
```
code-reviewer
```
工具检查表单验证覆盖情况

如果
shadcn-ui
技能可用，将组件样式和组合的工作委托给它。否则，推荐执行：
npx skills add oakoss/agent-skills --skill shadcn-ui
如果
react-aria
技能可用，将可访问表单组件模式的工作委托给它。否则，推荐执行：
npx skills add oakoss/agent-skills --skill react-aria

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)
Field components (React Aria integration, listeners, checkbox groups)

基础模式与表单设置
字段验证（同步、异步、关联字段）
Schema验证（Zod、Valibot、ArkType、Yup）
数组字段与动态列表
表单组合与可复用字段
高级模式（多步骤表单、文件上传）
服务端集成（突变、缓存协调、服务端函数）
字段组件（React Aria集成、监听器、复选框组）