React Hook Form Best Practices

Comprehensive performance optimization guide for React Hook Form applications. Contains 41 rules across 8 categories, prioritized by impact to guide form development, automated refactoring, and code generation.

When to Apply

Reference these guidelines when:

• Writing new forms with React Hook Form

• Configuring useForm options (mode, defaultValues, validation)

• Subscribing to form values with watch/useWatch

• Integrating controlled UI components (MUI, shadcn, Ant Design)

• Managing dynamic field arrays with useFieldArray

• Reviewing forms for performance issues

Rule Categories by Priority

Priority Category Impact Prefix

1 Form Configuration CRITICAL formcfg-

2 Field Subscription CRITICAL sub-

3 Controlled Components HIGH ctrl-

4 Validation Patterns HIGH valid-

5 Field Arrays MEDIUM-HIGH array-

6 State Management MEDIUM formstate-

7 Integration Patterns MEDIUM integ-

8 Advanced Patterns LOW adv-

Quick Reference

1. Form Configuration (CRITICAL)

• formcfg-validation-mode

• Use onSubmit mode for optimal performance

• formcfg-revalidate-mode

• Set reValidateMode to onBlur for post-submit performance

• formcfg-default-values

• Always provide defaultValues for form initialization

• formcfg-async-default-values

• Use async defaultValues for server data

• formcfg-should-unregister

• Enable shouldUnregister for dynamic form memory efficiency

• formcfg-useeffect-dependency

• Avoid useForm return object in useEffect dependencies

2. Field Subscription (CRITICAL)

• sub-usewatch-over-watch

• Use useWatch instead of watch for isolated re-renders

• sub-watch-specific-fields

• Watch specific fields instead of entire form

• sub-usewatch-with-getvalues

• Combine useWatch with getValues for timing safety

• sub-deep-subscription

• Subscribe deep in component tree where data is needed

• sub-avoid-watch-in-render

• Avoid calling watch() in render for one-time reads

• sub-usewatch-default-value

• Provide defaultValue to useWatch for initial render

• sub-useformcontext-sparingly

• Use useFormContext sparingly for deep nesting

3. Controlled Components (HIGH)

• ctrl-usecontroller-isolation

• Use useController for re-render isolation

• ctrl-avoid-double-registration

• Avoid double registration with useController

• ctrl-controller-field-props

• Wire Controller field props correctly for UI libraries

• ctrl-single-usecontroller-per-component

• Use single useController per component

• ctrl-local-state-combination

• Combine local state with useController for UI-only state

4. Validation Patterns (HIGH)

• valid-resolver-caching

• Define schema outside component for resolver caching

• valid-dynamic-schema-factory

• Use schema factory for dynamic validation

• valid-error-message-strategy

• Access errors via optional chaining or lodash get

• valid-inline-vs-resolver

• Prefer resolver over inline validation for complex rules

• valid-delay-error

• Use delayError to debounce rapid error display

• valid-native-validation

• Consider native validation for simple forms

5. Field Arrays (MEDIUM-HIGH)

• array-use-field-id-as-key

• Use field.id as key in useFieldArray maps

• array-complete-default-objects

• Provide complete default objects for field array operations

• array-separate-crud-operations

• Separate sequential field array operations

• array-unique-fieldarray-per-name

• Use single useFieldArray instance per field name

• array-virtualization-formprovider

• Use FormProvider for virtualized field arrays

6. State Management (MEDIUM)

• formstate-destructure-formstate

• Destructure formState properties before render

• formstate-useformstate-isolation

• Use useFormState for isolated state subscriptions

• formstate-getfieldstate-for-single-field

• Use getFieldState for single field state access

• formstate-subscribe-to-specific-fields

• Subscribe to specific field names in useFormState

• formstate-avoid-isvalid-with-onsubmit

• Avoid isValid with onSubmit mode for button state

7. Integration Patterns (MEDIUM)

• integ-shadcn-form-import

• Verify shadcn Form component import source

• integ-shadcn-select-wiring

• Wire shadcn Select with onValueChange instead of spread

• integ-mui-controller-pattern

• Use Controller for Material-UI components

• integ-value-transform

• Transform values at Controller level for type coercion

8. Advanced Patterns (LOW)

• adv-formprovider-memo

• Wrap FormProvider children with React.memo

• adv-devtools-performance

• Disable DevTools in production and during performance testing

• adv-testing-wrapper

• Create test wrapper with QueryClient and AuthProvider

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

• Reference files: references/{prefix}-{slug}.md

Related Skills

• For schema validation with Zod resolver, see zod skill

• For React 19 server actions, see react-19 skill

• For UI/UX form design, see frontend-design skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md