⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

TanStack Form 无头表单状态管理器 - 复杂表单验证与性能优化指南

tanstack-form by oakoss/agent-skills

49 周安装量

6 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/oakoss/agent-skills --skill tanstack-form

React 状态管理前端架构

🇨🇳中文介绍

TanStack Form

概述

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

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

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

React 编译器： TanStack Form 目前尚不兼容 React 编译器。请在使用 TanStack Form API 的文件或组件中禁用 React 编译器。

快速参考

模式	API	要点
基础表单	`useForm({ defaultValues, onSubmit })`	使用 Field 组件的表单实例
字段	带有 `name` 和 `children` 渲染函数的 `form.Field`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

网页可访问性（A11y）开发指南：实现WCAG合规、键盘导航与屏幕阅读器支持

12,600 周安装

UI组件模式实战指南：构建可复用React组件库与设计系统

10,700 周安装

Vercel React 最佳实践指南 | Next.js 性能优化与代码规范

10,600 周安装

React视图过渡API使用指南：实现原生浏览器动画与状态管理

9,100 周安装

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

如果 shadcn-ui 技能可用，请将组件样式和组合委托给它。否则，建议：npx skills add oakoss/agent-skills --skill shadcn-ui

如果 tanstack-query 技能可用，请将缓存管理和变更模式委托给它。如果 tanstack-start 技能可用，请将服务器函数和服务器端表单提交委托给它。如果 tanstack-router 技能可用，请将提交后导航和路由模式委托给它。如果 tanstack-devtools 技能可用，请将表单状态调试委托给它。

🇺🇸English

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

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

Weekly Installs

Repository

oakoss/agent-skills

GitHub Stars

First Seen

Feb 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

github-copilot45

gemini-cli45

codex45

kimi-cli45

amp45

cursor45

TanStack Form 无头表单状态管理器 - 复杂表单验证与性能优化指南

🇨🇳中文介绍

TanStack Form

概述

快速参考

相关 Skills

常见错误

委托

参考

🇺🇸English

TanStack Form

Overview

Quick Reference

Common Mistakes

Delegation

References

最新 Skills