Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill tanstack-form -a claude-code
Open on GitHub

What 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 hobbies field 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-code

2Manually: put the files in place

~/.claude/skills/tanstack-form/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-form/

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.

From the same set106

The whole set →
tailwind A Tailwind CSS v4 skill for themes, components, dark mode, container queries, v3 migrations, shadcn/ui, and build troubleshooting. CX Codex +1 233installs vitest-testing vitest-testing adds Vitest patterns and best practices to Claude Code. Helps write reliable unit, component, and hook tests without typical async mistakes. CX Codex +1 226installs content-humanizer content-humanizer rewrites model-written drafts so they read like a person wrote them: sentence rhythm, tone, and the hedging that gives AI text away. CX Codex +1 225installs zod-validation zod-validation guides AI coding agents through Zod v4 schema validation in TypeScript. Helps write schemas, parse incoming payloads, and generate JSON Schema definitions. CX Codex +1 222installs knowledge-graph-builder The knowledge-graph-builder skill guides knowledge-graph design, graph database choice, and graph-plus-vector retrieval. Use it for Graph RAG, entity resolution, and fact checks. CX Codex +1 222installs pino-logging Set up structured Pino logging in Node.js, including request context, sensitive-field redaction, transports, and framework integrations. CX Codex +1 217installs database-security database-security audits the data layer of Supabase, Postgres and Convex apps: RLS coverage, policy holes, service-role leaks, audit logging. Useful before a release or after an incident. CX Codex +1 208installs typescript-patterns Provides advanced strict-mode TypeScript patterns to enforce type safety and stop runtime errors before code runs. CX Codex +1 202installs

Project sponsors

Companies that keep this analytics open