Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-skillclaw-36k/skillsmp/react-hook-form/AGENTS.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill react-hook-form. Copyright stays with the author.

React Hook Form

Version 0.1.0
Community
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive performance optimization guide for React Hook Form applications, designed for AI agents and LLMs. Contains 41 rules across 8 categories, prioritized by impact from critical (form configuration, field subscriptions) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Form Configuration — CRITICAL
   • 1.1 Always Provide defaultValues for Form Initialization — CRITICAL (prevents undefined state bugs and enables reset() functionality)
   • 1.2 Avoid useForm Return Object in useEffect Dependencies — CRITICAL (prevents infinite render loops)
   • 1.3 Enable shouldUnregister for Dynamic Form Memory Efficiency — HIGH (reduces memory usage for forms with frequently mounted/unmounted fields)
   • 1.4 Set reValidateMode to onBlur for Post-Submit Performance — CRITICAL (reduces re-renders after initial submission by 80%+)
   • 1.5 Use Async defaultValues for Server Data — CRITICAL (eliminates manual useEffect reset patterns)
   • 1.6 Use onSubmit Mode for Optimal Performance — CRITICAL (prevents re-renders on every keystroke)
2. Field Subscription — CRITICAL
   • 2.1 Avoid Calling watch() in Render for One-Time Reads — HIGH (prevents unnecessary subscriptions and re-renders)
   • 2.2 Combine useWatch with getValues for Timing Safety — HIGH (prevents missed updates due to subscription timing)
   • 2.3 Provide defaultValue to useWatch for Initial Render — MEDIUM-HIGH (prevents undefined flash on initial render)
   • 2.4 Subscribe Deep in Component Tree Where Data Is Needed — CRITICAL (prevents parent re-renders from propagating to unrelated children)
   • 2.5 Use useFormContext Sparingly for Deep Nesting — MEDIUM (reduces prop drilling but increases implicit dependencies)
   • 2.6 Use useWatch Instead of watch for Isolated Re-renders — CRITICAL (reduces re-renders by 10-50× in complex forms with multiple watchers)
   • 2.7 Watch Specific Fields Instead of Entire Form — CRITICAL (reduces re-renders from N fields to 1 field change)
3. Controlled Components — HIGH
   • 3.1 Avoid Double Registration with useController — HIGH (prevents duplicate state management and validation bugs)
   • 3.2 Combine Local State with useController for UI-Only State — MEDIUM (reduces form re-renders by 50%+ when UI state changes don't affect form data)
   • 3.3 Use Single useController Per Component — MEDIUM-HIGH (prevents prop name collisions and simplifies component logic)
   • 3.4 Use useController for Re-render Isolation in Controlled Components — HIGH (reduces re-renders from O(n) to O(1) per field change)
   • 3.5 Wire Controller Field Props Correctly for UI Libraries — HIGH (prevents form binding bugs and eliminates silent failures in 100% of UI library integrations)
4. Validation Patterns — HIGH
   • 4.1 Access Errors via Optional Chaining or Lodash Get — MEDIUM-HIGH (prevents runtime errors from undefined nested properties)
   • 4.2 Consider Native Validation for Simple Forms — MEDIUM (reduces JavaScript validation overhead for basic constraints)
   • 4.3 Define Schema Outside Component for Resolver Caching — HIGH (prevents schema recreation on every render)
   • 4.4 Prefer Resolver Over Inline Validation for Complex Rules — HIGH (centralizes validation logic and enables type inference)
   • 4.5 Use delayError to Debounce Rapid Error Display — MEDIUM (reduces UI flicker during fast typing validation)
   • 4.6 Use Schema Factory for Dynamic Validation — HIGH (enables context-dependent validation without render-time schema creation)
5. Field Arrays — MEDIUM-HIGH
   • 5.1 Provide Complete Default Objects for Field Array Operations — HIGH (prevents partial data and validation failures)
   • 5.2 Separate Sequential Field Array Operations — MEDIUM-HIGH (prevents state corruption from batched mutations)
   • 5.3 Use field.id as Key in useFieldArray Maps — MEDIUM-HIGH (prevents state corruption and unnecessary re-renders)
   • 5.4 Use FormProvider for Virtualized Field Arrays — MEDIUM (maintains field state when rows exit/enter viewport)
   • 5.5 Use Single useFieldArray Instance Per Field Name — MEDIUM-HIGH (prevents state conflicts from duplicate subscriptions)
6. State Management — MEDIUM
   • 6.1 Avoid isValid with onSubmit Mode for Button State — MEDIUM (prevents validation on every render for button disabled state)
   • 6.2 Destructure formState Properties Before Render — MEDIUM (enables Proxy subscription optimization)
   • 6.3 Subscribe to Specific Field Names in useFormState — MEDIUM (reduces re-renders to only relevant field changes)
   • 6.4 Use getFieldState for Single Field State Access — MEDIUM (avoids subscription overhead for one-time state reads)
   • 6.5 Use useFormState for Isolated State Subscriptions — MEDIUM (prevents parent re-renders from state access in children)
7. Integration Patterns — MEDIUM
   • 7.1 Transform Values at Controller Level for Type Coercion — MEDIUM (prevents type coercion bugs in 100% of numeric/date form fields)
   • 7.2 Use Controller for Material-UI Components — MEDIUM (maintains controlled component behavior with proper event handling)
   • 7.3 Verify shadcn Form Component Import Source — MEDIUM (prevents silent component mismatch bugs)
   • 7.4 Wire shadcn Select with onValueChange Instead of Spread — MEDIUM (prevents 100% of silent select binding failures with Radix-based components)
8. Advanced Patterns — LOW
   • 8.1 Create Test Wrapper with QueryClient and AuthProvider — LOW (enables proper hook testing with required context providers)
   • 8.2 Disable DevTools in Production and During Performance Testing — LOW (eliminates DevTools overhead during profiling)
   • 8.3 Wrap FormProvider Children with React.memo — LOW (prevents cascade re-renders from FormProvider state updates)

References

1. https://react-hook-form.com/docs
2. https://react-hook-form.com/advanced-usage
3. https://react-hook-form.com/docs/useform
4. https://react-hook-form.com/docs/usewatch
5. https://react-hook-form.com/docs/usecontroller
6. https://react-hook-form.com/docs/usefieldarray
7. https://react-hook-form.com/docs/useformstate
8. https://github.com/react-hook-form/resolvers
9. https://ui.shadcn.com/docs/components/form

Source Files

This document was compiled from individual reference files. For detailed editing or extension: