home / skills / fusengine / agents / react-forms

react-forms skill

unsafe

/plugins/react-expert/skills/react-forms

This skill guides you to implement TanStack Form v1 with type-safe validation and server actions, ensuring scalable forms across components.

npx playbooks add skill fusengine/agents --skill react-forms

Review the files below or copy the command above to add this skill to your agents.

Files (34)

SKILL.md

6.1 KB

---
name: react-forms
description: TanStack Form v1 - type-safe forms with Zod/Yup/Valibot validation, async validation, arrays, nested fields, React 19 Server Actions
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
---

# TanStack Form v1 Core Features

## Agent Workflow (MANDATORY)

Before ANY implementation, use `TeamCreate` to spawn 3 agents:

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:**
- Files < 100 lines (split at 90)
- 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

| Library | Adapter | Bundle Size |
|---------|---------|-------------|
| **Zod** | `zodValidator()` | ~12KB |
| **Yup** | `yupValidator()` | ~40KB |
| **Valibot** | `valibotValidator()` | ~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/server-action-form.md` | React 19 Server Actions |
| `templates/optimistic-form.md` | useOptimistic integration |
| `templates/nested-form.md` | Dot notation nested fields |
| `templates/search-form.md` | Debounced search |
| `templates/conditional-fields.md` | Show/hide based on values |
| `templates/form-composition.md` | Reusable field components |
| `templates/listeners-form.md` | Side effects & auto-save |
| `templates/linked-fields-form.md` | Cross-field validation |
| `templates/reactivity-form.md` | Performance optimization |
| `templates/reset-form.md` | Form/field reset patterns |
| `templates/ssr-form.md` | SSR & hydration |
| `templates/devtools-form.md` | Devtools integration |
| `templates/react-native-form.md` | React Native forms |

---

## Best Practices

1. **Validation**: Use Zod/Yup/Valibot, NOT custom regex
2. **Async**: Debounce server validation (300-500ms)
3. **Errors**: Display `field.state.meta.errors`
4. **Nested**: Use dot notation (`address.street`)
5. **Arrays**: Use `mode="array"` with pushValue/removeValue
6. **TypeScript**: Infer types with `z.infer<typeof schema>`

---

## Forbidden (Anti-Patterns)

- ❌ `useState` for form state → use `useForm()`
- ❌ Regex validation → use Zod/Yup/Valibot
- ❌ No debounce on async → use `onChangeAsyncDebounceMs`
- ❌ Validation in components → move to schema
- ❌ Direct `onChange` → use `field.handleChange`
- ❌ No TypeScript types → use `z.infer<typeof schema>`

Overview

This skill provides a TypeScript-first integration of TanStack Form v1 for type-safe forms, with adapters for Zod, Yup, and Valibot, plus async validation, arrays, nested fields, and React 19 Server Actions. It focuses on predictable, performant form state and validation patterns for web and mobile apps. The implementation follows SOLID principles and offers templates and hooks for common form scenarios.

How this skill works

useForm initializes form state and validation using chosen schema adapters. useField and form.Field subscribe to individual fields with granular reactivity while form.Subscribe watches form-level changes. Validation adapters (zodValidator, yupValidator, valibotValidator) provide type inference and consistent error shapes; async server checks are debounced and integrate with useActionState for React 19 Server Actions.

When to use it

Building type-safe forms with full TypeScript inference from validation schemas
Implementing server-side async validation (debounced) or React 19 Server Actions
Managing dynamic arrays, deep nested fields, or linked cross-field validation
Optimizing performance with granular subscriptions and reactivity selectors
Integrating with shadcn/ui, React Native TextInput, or progressive enhancement flows

Best practices

Always use a validation library (Zod/Yup/Valibot); avoid custom regex.
Debounce async validation (300–500ms) and show loading states for server checks.
Follow SOLID rules: keep files small (<100 lines), place interfaces under modules/[feature]/src/interfaces/, and keep business logic out of components.
Document exports with JSDoc and infer types via z.infer<typeof schema> or equivalent.
Use field.handleChange, mode="array" for dynamic lists, and dot notation for nested fields (e.g., address.street).

Example use cases

Login/signup form with Zod schema and full type inference
Multi-step wizard with per-step validation and transition guards
Dynamic field arrays (add/remove items) for repeatable inputs
File upload with preview and validation before submit
Server-action-backed search or form with optimistic UI and debounced queries

FAQ

Which validator should I pick for bundle size and features?

Valibot is smallest, Zod balances size and ergonomics, and Yup is larger but familiar; choose based on team preference and required features.

How do I perform server-side async validation safely?

Use debounced async checks (300–500ms), show loading state, cancel stale requests, and validate again on submit on the server-side.