react-hook-form

Files (41)

• AGENTS.md
• README.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• array-disabled-silently-noops.md · references/
• array-separate-crud-operations.md · references/
• array-unique-fieldarray-per-name.md · references/
• array-use-field-id-as-key.md · references/
• ctrl-controller-field-props.md · references/
• ctrl-usecontroller-isolation.md · references/
• formcfg-async-default-values.md · references/
• formcfg-default-values.md · references/
• formcfg-disabled-prop.md · references/
• formcfg-revalidate-mode.md · references/
• formcfg-should-unregister.md · references/
• formcfg-transformed-values-generic.md · references/
• formcfg-useeffect-dependency.md · references/
• formcfg-validation-mode.md · references/
• formcfg-values-prop.md · references/
• formstate-async-submit-lifecycle.md · references/
• formstate-avoid-isvalid-with-onsubmit.md · references/
• formstate-destructure-formstate.md · references/
• formstate-handlesubmit-oninvalid.md · references/
• formstate-reset-default-values.md · references/
• formstate-useformstate-isolation.md · references/
• integ-shadcn-form-import.md · references/
• integ-shadcn-select-wiring.md · references/
• integ-value-transform.md · references/
• sub-avoid-watch-in-render.md · references/
• sub-memo-cannot-beat-context.md · references/
• sub-render-prop-components.md · references/
• sub-subscribe-outside-react.md · references/
• sub-useformcontext-sparingly.md · references/
• sub-usewatch-over-watch.md · references/
• sub-watch-specific-fields.md · references/
• valid-delay-error.md · references/
• valid-resolver-caching.md · references/
• valid-server-errors.md · references/
• valid-valueasnumber-empty-nan.md · references/

SKILL.md (first lines)

# React Hook Form Best Practices by Community

Comprehensive performance optimization guide for React Hook Form applications. Contains 35 rules across 7 categories, each naming a decision that goes wrong by default. Verified against react-hook-form **7.82.0**.

## 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 / subscribe
- Integrating controlled UI components (MUI, shadcn, Ant Design)
- Managing dynamic field arrays with useFieldArray
- Handling async submit, server errors, and submit lifecycle state
- Reviewing forms for performance issues

## When NOT to Use This Skill

- **React 19 Server Actions / `useActionState`** — use the `react-19` skill instead
- **Deeply nested, fully type-safe forms** — TanStack Form may be a better fit for forms with complex nested schemas; this skill assumes you've already chosen RHF
- **Single-input or trivial forms** — uncontrolled `<form>` + `FormData` is often simpler than pulling in any library

## 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 | State Management | MEDIUM-HIGH | `formstate-` |
| 6 | Field Arrays | MEDIUM-HIGH | `array-` |
| 7 | Integration Patterns | MEDIUM | `integ-` |

## Quick Reference

### 1. Form Configuration (CRITICAL)

- `formcfg-default-values` - Always Provide defaultValues for Form Initialization
- `formcfg-useeffect-dependency` - Depend on formState Slices, Not on formState Itself
- `formcfg-validation-mode` - Justify Any mode Other Than the Default onSubmit
- `formcfg-revalidate-mode` - Keep Default reValidateMode Unless Validation Is Expensive
- `formcfg-should-unregister` - Keep shouldUnregister Off Unless Hidden Fields Must Leave the Payload
- `formcfg-transformed-values-generic` - Pass the Third useForm Generic When the Resolver Transforms Values
- `formcfg-async-default-values` - Use Async defaultValues for Server Data
- `formcfg-disabled-prop` - Use the HTML disabled Attribute for Visual Disabling, Not register's disabled Option
- `formcfg-values-prop` - Use the values Prop to Keep a Form in Sync with Server Data

### 2. Field Subscription (CRITICAL)

- `sub-avoid-watch-in-render` - Avoid Calling watch() in Render for One-Time Reads
- `sub-memo-cannot-beat-context` - React.memo Cannot Stop Context-Driven Re-renders Under FormProvider
- `sub-subscribe-outside-react` - Use subscribe() to React to Form Changes Outside the React Lifecycle
- `sub-render-prop-components` - Use the Render-Prop Components to Isolate Re-renders Without a Child Component
- `sub-useformcontext-sparingly` - Use useFormContext Sparingly for Deep Nesting
- `sub-usewatch-over-watch` - Use useWatch Instead of watch for Isolated Re-renders
- `sub-watch-specific-fields` - Watch Specific Fields Instead of Entire Form

### 3. Controlled Components (HIGH)

- `ctrl-usecontroller-isolation` - Isolate Controlled Inputs in Dedicated Child Components
- `ctrl-controller-field-props` - Wire Controller Field Props Correctly for UI Libraries

### 4. Validation Patterns (HIGH)

- `valid-resolver-caching` - Build the Validation Schema Once, Outside the Render Path
- `valid-valueasnumber-empty-nan` - Handle the NaN valueAsNumber Produces for an Empty Input
- `valid-server-errors` - Surface Server Errors via setError('root.serverError', ...)
- `valid-delay-error` - Use delayError to Debounce Rapid Error Display

### 5. State Management (MEDIUM-HIGH)

- `formstate-avoid-isvalid-with-onsubmit` - Avoid isValid with onSubmit Mode for Button State
- `formstate-destructure-formstate` - Read Every formState Property You Depend On During Render
- `formstate-reset-default-values` - Rebase Defaults with resetDefaultValues After a Successful Save
- `formstate-handlesubmit-oninvalid` - Use handleSubmit's Second Argument to Handle a Rejected Submit
- `formstate-useformstate-isolation` - Use useFormState for Isolated State Subscriptions
- `formstate-async-submit-lifecycle` - Wrap Async Submit Handlers in try/catch and Reset on isSubmitSuccessful

### 6. Field Arrays (MEDIUM-HIGH)

- `array-separate-crud-operations` - Separate Sequential Field Array Operations
- `array-use-field-id-as-key` - Use field.id as Key in useFieldArray Maps
- `array-unique-fieldarray-per-name` - Use Single useFieldArray Instance Per Field Name
- `array-disabled-silently-noops` - useFieldArray's disabled Option Makes Every Mutation a Silent No-op

### 7. Integration Patterns (MEDIUM)

- `integ-value-transform` - Transform Values at Controller Level for Type Coercion
- `integ-shadcn-form-import` - Verify shadcn Form Component Import Source
- `integ-shadcn-select-wiring` - Wire shadcn Select with onValueChange Instead of Spread

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - 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`

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills