tanstack-form

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Form

Use this skill when work touches TanStack Form v1, especially

@tanstack/react-form

, form state, validation, reusable app form hooks, SSR adapters, or migrations from ad hoc React form handling.

当你处理TanStack Form v1相关工作时使用此技能，尤其是涉及

@tanstack/react-form

、表单状态、验证、可复用应用表单钩子、SSR适配器，或是从临时React表单处理方案迁移的场景。

Workflow

工作流程

Inspect the local form stack before changing code:
- Package versions for
```
@tanstack/react-form
```
  ,
```
@tanstack/form-core
```
  , SSR adapters, devtools, React, schema libraries, UI libraries, and test utilities.
- Form pattern: one-off
```
useForm
```
  , app-wide
```
createFormHook
```
  , nested
```
withForm
```
  , reusable
```
withFieldGroup
```
  , SSR adapter forms, or React Native.
- Validation intent: field-level, form-level, Standard Schema, async validators, dynamic revalidation, server validation, or submit-time errors.
- Rendering contract: controlled fields, labels, error display, focus management, submit state, and accessibility expectations.
Refresh current docs and package evidence when behavior or versions matter. Start from source-map.md.
For installation, core APIs,
```
useForm
```
,
```
form.Field
```
,
```
createFormHook
```
, app fields, subscriptions, async defaults, and UI-library wiring, use setup-core.md.
For field/form validators, Standard Schema, async validation, dynamic validation, server errors, custom errors, submit metadata, and transformed values, use validation-state.md.
For large forms, reusable app form hooks,
```
withForm
```
,
```
withFieldGroup
```
, arrays,
```
FormGroup
```
, linked fields, and listeners, use composition-arrays-groups.md.
For TanStack Start, Next.js App Router, Remix, server validation, devtools, debugging, accessibility, and production checks, use ssr-production.md.

在修改代码前检查本地表单栈：
- ```
@tanstack/react-form
```
  、
```
@tanstack/form-core
```
  、SSR适配器、开发工具、React、Schema库、UI库及测试工具的包版本。
- 表单模式：一次性
```
useForm
```
  、全局
```
createFormHook
```
  、嵌套
```
withForm
```
  、可复用
```
withFieldGroup
```
  、SSR适配器表单或React Native。
- 验证意图：字段级验证、表单级验证、Standard Schema验证、异步验证器、动态重新验证、服务端验证或提交时错误处理。
- 渲染约定：受控字段、标签、错误显示、焦点管理、提交状态及无障碍访问要求。
当行为或版本至关重要时，刷新最新文档和包相关参考。从source-map.md开始。
对于安装、核心API、
```
useForm
```
、
```
form.Field
```
、
```
createFormHook
```
、应用字段、订阅、异步默认值及UI库集成，请参考setup-core.md。
对于字段/表单验证器、Standard Schema、异步验证、动态验证、服务端错误、自定义错误、提交元数据及转换后的值，请参考validation-state.md。
对于大型表单、可复用应用表单钩子、
```
withForm
```
、
```
withFieldGroup
```
、数组、
```
FormGroup
```
、关联字段及监听器，请参考composition-arrays-groups.md。
对于TanStack Start、Next.js App Router、Remix、服务端验证、开发工具、调试、无障碍访问及生产环境检查，请参考ssr-production.md。

Implementation Judgment

实现判断

Prefer type inference from
```
defaultValues
```
or shared
```
formOptions
```
. Avoid adding broad
```
useForm<MyType>()
```
generics unless the local codebase already needs them.
Use plain
```
useForm
```
plus
```
form.Field
```
for small or one-off forms. For product forms and design-system integration, prefer
```
createFormHook
```
with pre-bound field and form components.
Treat TanStack Form fields as controlled fields. Wire
```
value
```
,
```
onBlur
```
, and
```
onChange
```
explicitly to the field API.
Subscribe deliberately. Use
```
form.Subscribe
```
for UI fragments and
```
useSelector(form.store, selector)
```
for component logic. Prefer
```
useSelector
```
over deprecated
```
useStore
```
. Avoid whole-store subscriptions.
Keep validation timing intentional. Choose
```
onChange
```
,
```
onBlur
```
,
```
onSubmit
```
,
```
onMount
```
,
```
onDynamic
```
, and async validators based on UX, not by habit.
Standard Schema validation checks input values; it does not hand transformed output to
```
onSubmit
```
. Parse inside
```
onSubmit
```
when transformed schema output matters.
Use
```
onChangeListenTo
```
or
```
onBlurListenTo
```
for cross-field validation and
```
listeners
```
for side effects such as resets, analytics, or autosave.
For multi-step forms, prefer
```
FormGroup
```
over separate isolated forms when one final submitted value and shared validation state are needed.
In SSR frameworks, share the form shape through adapter
```
formOptions
```
, validate server-side with
```
createServerValidate
```
, and merge returned form state with
```
mergeForm
```
plus
```
useTransform
```
.

优先从
```
defaultValues
```
或共享的
```
formOptions
```
进行类型推断。除非本地代码库确实需要，否则避免添加宽泛的
```
useForm<MyType>()
```
泛型。
小型或一次性表单使用普通的
```
useForm
```
搭配
```
form.Field
```
。对于产品表单和设计系统集成，优先使用预绑定字段和表单组件的
```
createFormHook
```
。
将TanStack Form字段视为受控字段。显式将
```
value
```
、
```
onBlur
```
和
```
onChange
```
连接到字段API。
谨慎使用订阅。UI片段使用
```
form.Subscribe
```
，组件逻辑使用
```
useSelector(form.store, selector)
```
。优先使用
```
useSelector
```
而非已弃用的
```
useStore
```
。避免全商店订阅。
保持验证时机的针对性。根据UX需求选择
```
onChange
```
、
```
onBlur
```
、
```
onSubmit
```
、
```
onMount
```
、
```
onDynamic
```
及异步验证器，而非凭习惯选择。
Standard Schema验证仅检查输入值；不会将转换后的输出传递给
```
onSubmit
```
。当转换后的Schema输出很重要时，在
```
onSubmit
```
内部进行解析。
跨字段验证使用
```
onChangeListenTo
```
或
```
onBlurListenTo
```
，重置、分析或自动保存等副作用使用
```
listeners
```
。
对于多步骤表单，当需要单一最终提交值和共享验证状态时，优先使用
```
FormGroup
```
而非单独的孤立表单。
在SSR框架中，通过适配器
```
formOptions
```
共享表单结构，使用
```
createServerValidate
```
进行服务端验证，并通过
```
mergeForm
```
搭配
```
useTransform
```
合并返回的表单状态。

Verification

验证

Prefer the repo's existing checks. For meaningful TanStack Form changes, include the relevant subset:

Typecheck for field names, deep keys, default values, validators, submit metadata, field groups, and SSR adapter imports.
Focused tests for validation timing, async debounce, submit errors, array mutations, linked fields, listener side effects, and reset/default behavior.
Browser smoke for controlled inputs, error rendering, disabled or aria-disabled submit behavior, focus on invalid submit, loading defaults, and server-returned errors.
SSR/action tests when changing TanStack Start, Next.js, or Remix adapter flows.
Devtools or debug inspection when state appears stale; form state is non-reactive unless explicitly subscribed.

优先使用仓库现有的检查。对于重要的TanStack Form变更，需包含以下相关子集：

类型检查：字段名称、深层键、默认值、验证器、提交元数据、字段组及SSR适配器导入。
针对性测试：验证时机、异步防抖、提交错误、数组变更、关联字段、监听器副作用及重置/默认行为。
浏览器冒烟测试：受控输入、错误渲染、禁用或aria-disabled提交行为、提交时聚焦无效字段、加载默认值及服务端返回的错误。
SSR/动作测试：当修改TanStack Start、Next.js或Remix适配器流程时。
开发工具或调试检查：当状态显示为过期时；表单状态除非显式订阅，否则是非响应式的。