AgentSkillsCN

react-hook-form

利用 useForm、useWatch、useController 和 useFieldArray，为客户端表单验证优化 React Hook Form 的性能。在使用 React Hook Form 库构建客户端受控表单时，应使用此技能。请注意，此技能并不涵盖 React 19 的服务器端操作、useActionState，或服务器端表单处理（此类功能请使用 react-19 技能）。

SKILL.md
--- frontmatter
name: react-hook-form
description: React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, and useFieldArray. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).

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

PriorityCategoryImpactPrefix
1Form ConfigurationCRITICALformcfg-
2Field SubscriptionCRITICALsub-
3Controlled ComponentsHIGHctrl-
4Validation PatternsHIGHvalid-
5Field ArraysMEDIUM-HIGHarray-
6State ManagementMEDIUMformstate-
7Integration PatternsMEDIUMinteg-
8Advanced PatternsLOWadv-

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