React Hook Form

# React Hook Form

**Version 1.2.0**  
Community  
May 2026

> **Note:** This document targets React Hook Form codebases.
> It is mainly for agents and LLMs to follow when maintaining, generating, or refactoring forms.
> 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 45 rules across 8 categories, prioritized by impact from critical (form configuration, field subscriptions, async submit lifecycle) to incremental (advanced patterns). Covers the v7.55+ `subscribe()` API, server error handling via `setError('root.*')`, and the `disabled` register option. 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](references/_sections.md#1-form-configuration) — **CRITICAL**
   - 1.1 [Always Provide defaultValues for Form Initialization](references/formcfg-default-values.md) — CRITICAL (prevents undefined state bugs and enables reset() functionality)
   - 1.2 [Avoid useForm Return Object in useEffect Dependencies](references/formcfg-useeffect-dependency.md) — CRITICAL (prevents infinite render loops)
   - 1.3 [Enable shouldUnregister for Dynamic Form Memory Efficiency](references/formcfg-should-unregister.md) — HIGH (reduces memory usage for forms with frequently mounted/unmounted fields)
   - 1.4 [Consider reValidateMode for Expensive Validation](references/formcfg-revalidate-mode.md) — MEDIUM (trade-off between immediate corrective feedback and validation cost)
   - 1.5 [Understand That register's disabled Prop Clears the Value](references/formcfg-disabled-prop.md) — MEDIUM (prevents lost field values and silently skipped validation)
   - 1.6 [Use Async defaultValues for Server Data](references/formcfg-async-default-values.md) — CRITICAL (eliminates manual useEffect reset patterns)
   - 1.7 [Use onSubmit Mode for Optimal Performance](references/formcfg-validation-mode.md) — CRITICAL (prevents re-renders on every keystroke)
2. [Field Subscription](references/_sections.md#2-field-subscription) — **CRITICAL**
   - 2.1 [Avoid Calling watch() in Render for One-Time Reads](references/sub-avoid-watch-in-render.md) — HIGH (prevents unnecessary subscriptions and re-renders)
   - 2.2 [Combine useWatch with getValues for Timing Safety](references/sub-usewatch-with-getvalues.md) — HIGH (prevents missed updates due to subscription timing)
   - 2.3 [Provide defaultValue to useWatch for Initial Render](references/sub-usewatch-default-value.md) — MEDIUM-HIGH (prevents undefined flash on initial render)
   - 2.4 [Subscribe Deep in Component Tree Where Data Is Needed](references/sub-deep-subscription.md) — CRITICAL (prevents parent re-renders from propagating to unrelated children)
   - 2.5 [Use subscribe() to React to Form Changes Outside the React Lifecycle](references/sub-subscribe-outside-react.md) — HIGH (zero re-renders for non-UI consumers like analytics, autosave, telemetry)
   - 2.6 [Use useFormContext Sparingly for Deep Nesting](references/sub-useformcontext-sparingly.md) — MEDIUM (reduces prop drilling but increases implicit dependencies)
   - 2.7 [Use useWatch Instead of watch for Isolated Re-renders](references/sub-usewatch-over-watch.md) — CRITICAL (reduces re-renders by 10-50× in complex forms with multiple watchers)
   - 2.8 [Watch Specific Fields Instead of Entire Form](references/sub-watch-specific-fields.md) — CRITICAL (reduces re-renders from N fields to 1 field change)
3. [Controlled Components](references/_sections.md#3-controlled-components) — **HIGH**
   - 3.1 [Avoid Double Registration with useController](references/ctrl-avoid-double-registration.md) — HIGH (prevents duplicate state management and validation bugs)
   - 3.2 [Combine L