TanStack Form for Next.js 16

Type-safe, performant forms with Server Actions and signal-based reactivity.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

• fuse-ai-pilot:explore-codebase - Analyze existing forms and validation patterns

• fuse-ai-pilot:research-expert - Verify latest TanStack Form docs via Context7/Exa

• mcp__context7__query-docs - Check form options and field API

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

Overview

When to Use

• Building forms with complex validation requirements

• Need Server Actions integration for form submission

• Implementing multi-step wizards or dynamic field arrays

• Require real-time async validation (username availability)

• Want type-safe forms with full TypeScript inference

Why TanStack Form

Feature Benefit

Signal-based state Minimal re-renders, optimal performance

Full TypeScript DeepKeys, DeepValue inference

Server Actions native Built-in Next.js 16 integration

Zod adapter Schema-first validation

Framework agnostic Same API for React, Vue, Solid

Headless Works with any UI library (shadcn/ui)

Critical Rules

• formOptions shared - Define once, use in client and server

• Server validation - DB checks in onServerValidate , not client

• Zod schemas - Client-side instant feedback

• useActionState - React 19 hook for Server Actions

• mergeForm - Combine server errors with client state

• SOLID paths - Forms in modules/[feature]/src/components/forms/

SOLID Architecture

Module Structure

Forms organized by feature module:

• modules/auth/src/components/forms/

• Auth forms (login, signup)

• modules/auth/src/interfaces/

• Form types and schemas

• modules/auth/src/actions/

• Server Actions for form submission

• modules/cores/lib/forms/

• Shared form utilities

File Organization

File Purpose Max Lines

form-options.ts

Shared formOptions + Zod schema 50

FormComponent.tsx

Client form UI with fields 80

form.action.ts

Server Action with validation 30

form.interface.ts

Types for form values 30

Key Concepts

Form Options Pattern

Define form configuration once, share between client and server. Ensures type safety and consistency.

Field API

Each field has state (value, errors, touched, validating) and handlers (handleChange, handleBlur).

Validation Levels

• onChange - Real-time as user types

• onBlur - When field loses focus

• onSubmit - Before form submission

• onServer - Server-side in action

Error Management

Errors exist at field-level and form-level. Use field.state.meta.errors for field errors, form.state.errorMap for form errors.

Reference Guide

Need Reference

Initial setup installation.md

Basic patterns basic-usage.md, field-api.md

Validation validation-zod.md, async-validation.md

Server Actions server-actions.md

Dynamic forms array-fields.md, multi-step-form.md

UI integration shadcn-integration.md

TypeScript typescript.md

Migration migration-rhf.md

Best Practices

• Define schemas first - Zod schemas drive both validation and types

• Shared formOptions - Single source of truth for client/server

• Debounce async validation - Use asyncDebounceMs for API calls

• form.Subscribe - Selective re-renders for submit state

• Field composition - Reusable field components with shadcn/ui

• Server errors merge - Use mergeForm to show server validation errors

Comparison vs React Hook Form

Aspect TanStack Form React Hook Form

Type Safety 100% (DeepKeys) Manual typing

Performance Signals (minimal) Refs (good)

Server Actions Native support Manual integration

Bundle Size ~12KB ~9KB

Learning Curve Medium Low

Use Case Complex apps Standard forms