react-forms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Form v1 Core Features

TanStack Form v1 核心特性

Agent Workflow (MANDATORY)

Agent 工作流（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing form components and validation patterns
fuse-ai-pilot:research-expert - Verify latest TanStack Form v1 docs via Context7/Exa
mcp__context7__query-docs - Check Zod validation and React 19 Server Actions patterns

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有表单组件和验证模式
fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新TanStack Form v1文档
mcp__context7__query-docs - 检查Zod验证和React 19 Server Actions模式

实现完成后，运行fuse-ai-pilot:sniper进行验证。

MANDATORY: SOLID Principles

强制要求：SOLID原则

ALWAYS apply SOLID principles from
solid-react
skill.

→ See

../solid-react/SKILL.md

for complete rules

Key Rules:

Files < 100 lines (split at 90)
Interfaces in
```
modules/[feature]/src/interfaces/
```
JSDoc mandatory on all exports
No business logic in components

始终遵循
solid-react
技能中的SOLID原则。

→ 完整规则请查看

../solid-react/SKILL.md

核心规则：

文件行数<100行（90行时拆分）
接口放在
```
modules/[feature]/src/interfaces/
```
目录下
所有导出内容必须添加JSDoc注释
组件中不得包含业务逻辑

Core Hooks

核心Hook

Hook	Purpose	Guide
`useForm()`	Initialize form with validation	`references/tanstack-form-basics.md`
`useField()`	Subscribe to individual field	`references/tanstack-form-basics.md`
`form.Field`	Render prop component for fields	`references/tanstack-form-basics.md`
`form.Subscribe`	Watch form state changes	`references/tanstack-form-basics.md`

→ See

references/tanstack-form-basics.md

for detailed usage

Hook	用途	参考文档
`useForm()`	初始化带验证的表单	`references/tanstack-form-basics.md`
`useField()`	订阅单个字段	`references/tanstack-form-basics.md`
`form.Field`	用于字段的渲染属性组件	`references/tanstack-form-basics.md`
`form.Subscribe`	监听表单状态变化	`references/tanstack-form-basics.md`

→ 详细用法请查看

references/tanstack-form-basics.md

Validation Adapters

验证适配器

Library	Adapter	Bundle Size
Zod	`zodValidator()`	~12KB
Yup	`yupValidator()`	~40KB
Valibot	`valibotValidator()`	~6KB

→ See

references/zod-validation.md

for Zod patterns → See

references/yup-valibot.md

for alternatives

库	适配器	包大小
Zod	`zodValidator()`	~12KB
Yup	`yupValidator()`	~40KB
Valibot	`valibotValidator()`	~6KB

→ Zod模式请查看

references/zod-validation.md

→ 替代方案请查看

references/yup-valibot.md

Key Features

核心特性

Async Validation

异步验证

Server-side checks with debouncing and loading states. → See

references/async-validation.md

带防抖和加载状态的服务器端检查。 → 请查看

references/async-validation.md

Server Actions (React 19)

React 19 Server Actions

Integration with useActionState and progressive enhancement. → See

references/server-actions.md

与useActionState和渐进式增强集成。 → 请查看

references/server-actions.md

Arrays & Nested Fields

数组与嵌套字段

Dynamic field arrays and dot notation for nested objects. → See

references/arrays-nested.md

动态字段数组和用于嵌套对象的点表示法。 → 请查看

references/arrays-nested.md

TypeScript Integration

TypeScript集成

Full type inference from Zod schemas and defaultValues. → See

references/typescript.md

从Zod schema和defaultValues自动推断类型。 → 请查看

references/typescript.md

shadcn/ui Integration

shadcn/ui集成

Field wrapper components with shadcn styling. → See

references/shadcn-integration.md

带shadcn样式的字段包装组件。 → 请查看

references/shadcn-integration.md

Listeners (Side Effects)

监听器（副作用）

onMount, onChange, onBlur, onSubmit with debouncing. → See

references/listeners.md

带防抖的onMount、onChange、onBlur、onSubmit。 → 请查看

references/listeners.md

Linked Fields

关联字段

Cross-field validation and dependent dropdowns. → See

references/linked-fields.md

跨字段验证和依赖下拉框。 → 请查看

references/linked-fields.md

Reactivity & Performance

响应式与性能

useStore selectors and granular subscriptions. → See

references/reactivity.md

useStore选择器和细粒度订阅。 → 请查看

references/reactivity.md

Reset API

重置API

Form and field reset with custom values. → See

references/reset-api.md

带自定义值的表单和字段重置。 → 请查看

references/reset-api.md

SSR & Hydration

SSR与Hydration

TanStack Start integration and server state merge. → See

references/ssr-hydration.md

TanStack Start集成和服务器状态合并。 → 请查看

references/ssr-hydration.md

Devtools

开发者工具

Debug form state with @tanstack/react-form-devtools. → See

references/devtools.md

使用@tanstack/react-form-devtools调试表单状态。 → 请查看

references/devtools.md

React Native

Mobile-specific patterns with TextInput. → See

references/react-native.md

针对TextInput的移动端特定模式。 → 请查看

references/react-native.md

Standard Schema

标准Schema

ArkType and Effect Schema support. → See

references/standard-schema.md

支持ArkType和Effect Schema。 → 请查看

references/standard-schema.md

Templates

模板

Template	Use Case
`templates/basic-form.md`	Login/signup with Zod
`templates/multi-step-form.md`	Wizard with step validation
`templates/dynamic-fields.md`	Add/remove field arrays
`templates/file-upload-form.md`	File input with preview
`templates/server-action-form.md`	React 19 Server Actions
`templates/optimistic-form.md`	useOptimistic integration
`templates/nested-form.md`	Dot notation nested fields
`templates/search-form.md`	Debounced search
`templates/conditional-fields.md`	Show/hide based on values
`templates/form-composition.md`	Reusable field components
`templates/listeners-form.md`	Side effects & auto-save
`templates/linked-fields-form.md`	Cross-field validation
`templates/reactivity-form.md`	Performance optimization
`templates/reset-form.md`	Form/field reset patterns
`templates/ssr-form.md`	SSR & hydration
`templates/devtools-form.md`	Devtools integration
`templates/react-native-form.md`	React Native forms

模板	适用场景
`templates/basic-form.md`	基于Zod的登录/注册表单
`templates/multi-step-form.md`	带步骤验证的向导表单
`templates/dynamic-fields.md`	可添加/删除的字段数组
`templates/file-upload-form.md`	带预览的文件输入表单
`templates/server-action-form.md`	React 19 Server Actions表单
`templates/optimistic-form.md`	useOptimistic集成表单
`templates/nested-form.md`	点表示法嵌套字段表单
`templates/search-form.md`	防抖搜索表单
`templates/conditional-fields.md`	根据值显示/隐藏字段的表单
`templates/form-composition.md`	可复用字段组件表单
`templates/listeners-form.md`	副作用与自动保存表单
`templates/linked-fields-form.md`	跨字段验证表单
`templates/reactivity-form.md`	性能优化表单
`templates/reset-form.md`	表单/字段重置模式
`templates/ssr-form.md`	SSR与Hydration表单
`templates/devtools-form.md`	开发者工具集成表单
`templates/react-native-form.md`	React Native表单

Best Practices

最佳实践

Validation: Use Zod/Yup/Valibot, NOT custom regex
Async: Debounce server validation (300-500ms)
Errors: Display
```
field.state.meta.errors
```
Nested: Use dot notation (
```
address.street
```
)
Arrays: Use
```
mode="array"
```
with pushValue/removeValue
TypeScript: Infer types with
```
z.infer<typeof schema>
```

验证：使用Zod/Yup/Valibot，不要使用自定义正则
异步：对服务器验证添加防抖（300-500ms）
错误提示：显示
```
field.state.meta.errors
```
嵌套字段：使用点表示法（如
```
address.street
```
）
数组：使用
```
mode="array"
```
配合pushValue/removeValue
TypeScript：通过
```
z.infer<typeof schema>
```
推断类型

Forbidden (Anti-Patterns)

禁用项（反模式）

❌
```
useState
```
for form state → use
```
useForm()
```
❌ Regex validation → use Zod/Yup/Valibot
❌ No debounce on async → use
```
onChangeAsyncDebounceMs
```
❌ Validation in components → move to schema
❌ Direct
```
onChange
```
→ use
```
field.handleChange
```
❌ No TypeScript types → use
```
z.infer<typeof schema>
```

❌ 使用
```
useState
```
管理表单状态 → 请使用
```
useForm()
```
❌ 使用正则验证 → 请使用Zod/Yup/Valibot
❌ 异步验证不防抖 → 请使用
```
onChangeAsyncDebounceMs
```
❌ 在组件中进行验证 → 移至schema中
❌ 直接使用
```
onChange
```
→ 请使用
```
field.handleChange
```
❌ 不添加TypeScript类型 → 请使用
```
z.infer<typeof schema>
```