Overview :-
The useFormContext documentation page does not mention that accessing formState (such as errors) through useFormContext results in stale values that do not trigger re-renders. The correct approach is to use useFormState, but there is no guidance on this anywhere on the useFormContext page.
This is expected behavior, but currently undocumented, so a developer might encounter it.
Current Behaviour :-
// child component inside FormProvider tree
// errors is stale and does not update on validation
const { formState: { errors } } = useFormContext()
Expected/Correct Behaviour :-
// properly subscribes to errors inside FormProvider tree
const { errors } = useFormState()
Where the gap is :-
- /docs/useformcontext/ -> no mention of formState subscription behavior, no mention of useFormState
- /docs/useform/formstate/ -> documents the Proxy rule, but only in the context of useForm, not useFormContext
- /docs/useformstate/ -> no mention of useFormContext or when to prefer it
A developer reading only the useFormContext page has no reason to know this limitation exists or that useFormState is the solution.
Suggested Fix :-
Add a note to the useFormContext page:
When subscribing to formState values such as errors inside a FormProvider tree, use useFormState instead of destructuring from useFormContext. Due to the Proxy-based subscription model, formState accessed via useFormContext will not trigger re-renders on state changes.
I am happy to submit a PR for this if the maintainers confirm this is a gap worth addressing.