React Form Patterns
Standard stack: React Hook Form + Zod. Keep schema and UI behavior aligned.
Use This Skill When
- Building new forms with validation.
- Refactoring unstable form state logic.
- Implementing multi-step, dynamic, or async-validated forms.
Core Contract
- Keep schema as source of truth (Zod).
- Use typed form values inferred from schema.
- Validate at client and server boundaries.
- Separate field rendering from submit side effects.
- Keep form loading/error states explicit.
Implementation Workflow
1) Baseline Form
- Create Zod schema.
- Infer TypeScript type from schema.
- Initialize RHF with resolver and defaults.
- Render errors at field-level and form-level.
2) Advanced Patterns
- Multi-step:
- separate per-step schema
- aggregate typed payload
- explicit next/back transitions
- Dynamic arrays:
- use
useFieldArray - stable keys and predictable remove/append behavior
- Async validation:
- debounce expensive validators
- isolate network errors from sync schema errors
- File upload:
- validate type/size before submit
- keep upload state and retry logic explicit
3) Server Integration
- Normalize server errors to RHF-compatible shape.
- Keep optimistic UI optional and reversible.
- For server actions, preserve idempotent submit behavior.
UX and Accessibility Checklist
- Keyboard navigation works for all inputs.
- Error messages are specific and linked to fields.
- Submit button state reflects in-flight operations.
- Success and failure feedback is visible and deterministic.
Output Requirements for Agent
- Schema design.
- Form state model.
- Validation and submission flow.
- Error handling and accessibility checks.
References
- Detailed code templates (basic, shadcn, multi-step, arrays, uploads):
references/guide.md