/react-forms

name: react-forms
description: Use when building type-safe forms in React with TanStack Form v1 — Zod/Yup/Valibot validation, async validation, field arrays.
version: 1.0.0
user-invocable: true
references: references/tanstack-form-basics.md, references/zod-validation.md, references/async-validation.md, references/server-actions.md, references/arrays-nested.md, references/typescript.md, references/yup-valibot.md, references/shadcn-integration.md, references/listeners.md, references/linked-fields.md, references/reactivity.md, references/reset-api.md, references/ssr-hydration.md, references/devtools.md, references/react-native.md, references/standard-schema.md, references/templates/basic-form.md, references/templates/multi-step-form.md, references/templates/dynamic-fields.md, references/templates/file-upload-form.md, references/templates/server-action-form.md, references/templates/optimistic-form.md, references/templates/nested-form.md, references/templates/search-form.md, references/templates/conditional-fields.md, references/templates/form-composition.md, references/templates/listeners-form.md, references/templates/linked-fields-form.md, references/templates/reactivity-form.md, references/templates/reset-form.md, references/templates/ssr-form.md, references/templates/devtools-form.md, references/templates/react-native-form.md

<objective> Implements TanStack Form v1 in React: core hooks (`useForm()`, `useField()`, `form.Field`, `form.Subscribe`), native Standard Schema validation (Zod ~12KB, Yup ~40KB, Valibot ~6KB, ArkType, Effect Schema — no adapter package), debounced async validation, and React 19 Server Actions integration via `useActionState`.

Also covers array/nested fields with dot notation, listeners for side effects (onMount/onChange/onBlur with debouncing), linked/cross-field validation, reactivity via `useStore` selectors, the Reset API, SSR/hydration (TanStack Start), devtools, and React Native patterns. This is the React skill for TanStack Form — for the Next.js Server Actions-specific variant see nextjs-tanstack-form, and for SOLID file-organization rules see solid-react. </objective>

TanStack Form v1 Core Features

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

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

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

---

MANDATORY: SOLID Principles

**ALWAYS apply SOLID principles from `solid-react` skill.**

→ See `../solid-react/SKILL.md` for complete rules

**Key Rules:**

• Source files stay within `FUSE_SOLID_MAX_LINES` and split by responsibility when cohesion drops
• Interfaces in `modules/[feature]/src/interfaces/`
• JSDoc mandatory on all exports
• No business logic in components

---

Core Hooks

| 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

---

Validation Adapters

TanStack Form v1 (`@tanstack/react-form` 1.33.x) supports **Standard Schema natively** — pass the schema itself to `validators` (`onChange: userSchema`). No adapter: `validatorAdapter` and `@tanstack/zod-form-adapter` (last release 0.42.1, pre-v1, Zod 3 only) are removed/obsolete.

| Library | Usage | Min version | Bundle Size | |---------|-------|-------------|-------------| | **Zod** | `validators: { onChange: schema }` | 3.24.0 | ~12KB | | **Yup** | `validators: { onChange: schema }` | 1.7.0 | ~40KB | | **Valibot** | `validators: { onChange: schema }` | 1.0.0 | ~6KB |

→ See `references/zod-validation.md` for Zod patterns → See `references/yup-valibot.md` for alternatives

---

Key Features

Async Validation

Server-side checks with debouncing and loading states. → See `references/async-validation.md`

Server Actions (React 19)

Integration with useActionState and progressive enhancement. → See `references/server-actions.md`

Arrays & Nested Fields

Dynamic field arrays and dot notation for nested objects. → See `references/arrays-nested.md`

TypeScript Integration

Full type inference from Zod schemas and defaultValues. → See `references/typescript.md`

shadcn/ui Integration

Field wrapper components with shadcn styling. → See `references/shadcn-integration.md`

Listeners (Side Effects)

onMount, onChange, onBlur, onSubmit with debouncing. → See `references/listeners.md`

Linked Fields

Cross-field validation and dependent dropdowns. → See `references/linked-fields.md`

Reactivity & Performance

useStore selectors and granular subscriptions. → See `references/reactivity.md`

Reset API

Form and field reset with custom values. → See `references/reset-api.md`

SSR & Hydration

TanStack Start integration and server state merge. → See `references/ssr-hydration.md`

Devtools

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

React Native

Mobile-specific patterns with TextInput. → See `references/react-native.md`

Standard Schema

ArkType and Effect Schema support. → See `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/serv