tanstack-form · oakoss — Claude Code skill: forms and setup
This skill guides TanStack Form v1 usage in React, covering state, validation, and submission. Use it for complex forms and changing field lists.
MIT 222 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill tanstack-form -a claude-codeWhat tanstack-form does
This skill covers TanStack Form v1 as a headless state manager for React forms. It helps an agent wire field state, synchronous or asynchronous validation, debounced checks, submission, array fields, and dependencies between fields. You supply the inputs and event handlers yourself; TanStack Form handles the form logic rather than rendering a UI kit.
The material includes multi-step form patterns, reusable field groups, form sections, state subscriptions, and Standard Schema support. Zod, Valibot, ArkType, and Yup schemas can be passed directly. Task can handle complex cross-field validation work, while Explore can look for existing form implementations.
TanStack Form is not compatible with React Compiler yet. Disable React Compiler in files or components that use its APIs. For a plain form covered by native HTML validation, this skill brings more structure than you need.
What it helps with
- build a form with sync and async validation
- manage a dynamic list of fields
- revalidate one field when another changes
- split a large form into reusable sections
- connect Zod, Valibot, ArkType, or Yup schemas
Example prompts for the agent
- Build a React form with TanStack Form v1 and validate fields on change and submit.
- Add a dynamic
hobbiesfield array with controls for inserting and removing items. - Break the large form into reusable field groups and connect a Zod schema.
How to install tanstack-form
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-form -a claude-code2Manually: put the files in place
~/.claude/skills/tanstack-form/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tanstack-form/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-form -a codex2Manually: put the files in place
.agents/skills/tanstack-form/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-form -a cursor2Manually: put the files in place
.cursor/skills/tanstack-form/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/tanstack-form2Manually: put the files in place
.github/skills/tanstack-form/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-form -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/tanstack-formManually: put the files in place
.devin/skills/tanstack-form/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-form -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tanstack-form
How do I install tanstack-form in Claude Code?
Run npx skills add oakoss/agent-skills --skill tanstack-form -a claude-code, then check ~/.claude/skills/tanstack-form/SKILL.md.
What does tanstack-form do?
The skill helps an agent build React forms with TanStack Form v1, including state handling, validation, submission, array fields, linked fields, form composition, and Standard Schema support.
Does tanstack-form work with React Compiler?
No. React Compiler must be disabled for files or components that use TanStack Form APIs.
Source text
SKILL.md · MIT
---
name: tanstack-form
description: |
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.
license: MIT
metadata:
author: oakoss
version: '1.1'
source: 'https://tanstack.com/form/latest/docs'
user-invocable: false
---
# 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](references/basic-patterns.md)
- [Field validation (sync, async, linked fields)](references/validation.md)
- [Schema validation (Zod, Valibot, ArkType, Yup)](references/schema-validation.md)
- [Array fields and dynamic lists](references/array-fields.md)
- [Form composition and reusable fields](references/form-composition.md)
- [Advanced patterns (multi-step forms, file uploads)](references/advanced-patterns.md)
- [Server integration (mutations, cache coordination, server functions)](references/server-integration.md)
- [React Aria integration (TextField, Select, Switch, Checkbox, RadioGroup)](references/react-aria-integration.md)
- [shadcn/ui integration (Field layout, Input, Select, Switch, Checkbox, RadioGroup)](references/shadcn-integration.md)
© oakoss · MIT · oakoss/agent-skills
Similar skills
All skills for Frontend and UI →tanstack-form by other authors comes first.