docs(react): document field state reactivity by dgesteves · Pull Request #2445 · TanStack/form

dgesteves · 2026-10-24T15:46:45Z

🎯 Changes

Closes #1207.

The issue asks the docs to explain using useStore for field.state.meta in extracted field components, why meta goes stale without it, and to double check whether field.state.value needs it too. Before writing anything I checked this on current main. Since #1893, useField returns a new field object whenever the field's value or meta changes, and AppField passes that object through fieldContext, so a component using useFieldContext re-renders along with the field. That means field.state.value and field.state.meta are already up to date there, so the docs say that instead of describing meta as stale.

reactivity.md: new "Field state" section. Field state read inside form.Field and in useFieldContext components doesn't need useSelector or form.Subscribe. It also notes the mode="array" exception, which the existing "should not rerender array field when child field value changes" test covers, and shows useSelector(field.store, ...).
form-composition.md: the pre-bound TextField example now wires onBlur and shows the field's errors from field.state.meta, and links to the new section.

How I checked it: I wrote a throwaway vitest file (not included here) with a createFormHook field component that reads meta directly, a React.memo copy of it, and the useSelector(field.store, ...) snippet. It covers field onChange/onBlur validators, a form-level validator, and an async validator's isValidating. Every case passed both normally and with babel-plugin-react-compiler enabled. As a control, I switched useField back to returning the stable FieldApi (the pre-#1893 behavior), and the memoized component went stale, which is what the issue originally described. I also type-checked the snippets with strict tsc against the built @tanstack/react-form, and pnpm test:pr passes.

Happy to take suggested changes, for example if you'd rather field components use useSelector(field.store, ...) the way the large-form and multi-step-wizard examples do.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested code changes locally with pnpm test:pr, or these tests do not apply to this pull request.
I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Documentation
- Expanded the React form-composition guide with an example that handles input blur and displays validation errors.
- Added guidance on how field values and metadata trigger re-renders, including the behavior of array fields when item values change.
- Explained how to subscribe to field state, such as metadata, to keep displayed values in sync.

Explain that field state read inside `form.Field` and in field components using `useFieldContext` is kept up to date, note the array-mode exception, and show `useSelector(field.store, ...)`. Update the pre-bound `TextField` example to handle blur and show the field's errors. Closes TanStack#1207

changeset-bot · 2026-10-24T15:46:51Z

⚠️ No Changeset found

Latest commit: ebdd2bc

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-10-24T15:46:57Z

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: TanStack/form
Branch: main
File: .coderabbit.yaml
Commit: 2216fde
Layers: Repository YAML
Review profile: CHILL
Plan: Advanced
Run ID: a1ef10b7-e1e1-4710-a3a5-698da3c73b00

Commits

Reviewing files that changed from the base of the PR and between 62a9bdd and ebdd2bc.

Files selected for processing: 2

docs/framework/react/guides/form-composition.md
docs/framework/react/guides/reactivity.md

Files skipped from review as they are similar to previous changes: 1

docs/framework/react/guides/form-composition.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

Walkthrough

The React guides explain how field values and metadata trigger re-renders, describe array-field behavior, and show a field component that handles blur and displays validation errors.

Changes: React field state documentation

Layer / File(s)	Summary
Field reactivity and usage examples `docs/framework/react/guides/reactivity.md`, `docs/framework/react/guides/form-composition.md`	The Reactivity guide describes field state subscriptions, including the array-field exception and `useSelector`. The composition example marks the field touched on blur and displays nonempty errors with `role="alert"`.

Priority: Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Possibly related PRs

TanStack/form#2444: Updates array-field subscriptions so an array field rerenders when its own metadata errors change, matching the documented array-field behavior.

Suggested reviewers: lecarbonator

Merge Risk: Minimal · up to ebdd2

The documentation changes are mergeable with no identified correctness or operational risk.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Linked Issues check		Issue [`#1207`] requires documentation for field metadata reactivity, the stale-state cause, value reactivity, and related examples. The new docs show `useSelector(field.store, ...)` for `meta.errors` a…	Add a direct explanation of the subscription boundary and stale metadata behavior. State the verified behavior for `field.state.value` and `field.state.meta` in both `form.Field` render functions and `useFieldContext` components. Align the …

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title "docs(react): document field state reactivity" matches the main change: new field-state reactivity guidance in the React reactivity and form-composition docs. It is concise, follows a conven…
Description check		The description follows the template. It has a Changes section that explains the motivation (issue `#1207`), the finding that field state stays current in form.Field and useFieldContext components, the …
Out of Scope Changes check		The reviewed changes are limited to `reactivity.md` and `form-composition.md`. The new field-state guidance, `useSelector` example, blur handling, and error display all support issue [`#1207`]. No unrel…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Title check

Explanation

The title "docs(react): document field state reactivity" matches the main change: new field-state reactivity guidance in the React reactivity and form-composition docs. It is concise, follows a conventional-commit style, and names the affected framework. It does not mention the array-mode exception or the TextField example update, which is acceptable because the title need not cover every detail.

Full details: Description check

Explanation

The description follows the template. It has a Changes section that explains the motivation (issue #1207), the finding that field state stays current in form.Field and useFieldContext components, the files changed, and how the author verified the work. All three checklist items are checked. The release impact item marks the change as docs-only, which matches the diff. The description does not include a changeset, which is correct for a docs-only change.

Full details: Out of Scope Changes check

Explanation

The reviewed changes are limited to reactivity.md and form-composition.md. The new field-state guidance, useSelector example, blur handling, and error display all support issue [#1207]. No unrelated change is identified.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

Full details: Linked Issues check

Explanation

Issue [#1207] requires documentation for field metadata reactivity, the stale-state cause, value reactivity, and related examples. The new docs show useSelector(field.store, ...) for meta.errors and state that form.Field subscribes to its field. However, they do not explain why metadata becomes stale without a subscription. They also do not clearly state whether direct field.state.value reads in useFieldContext components remain current; the guide instead gives a selector for metadata while the example reads field.state.value directly. This leaves the requested value comparison unresolved.

Resolution

Add a direct explanation of the subscription boundary and stale metadata behavior. State the verified behavior for field.state.value and field.state.meta in both form.Field render functions and useFieldContext components. Align the TextField example and the reactivity guide with that explanation.

Finishing Touches

🧪 Generate unit tests (beta)

Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

LeCarbonator

Appreciate the docs addition! Some minor notes regarding useSelector, but the rest looks good!

nx-cloud · 2026-10-24T21:02:35Z

View your CI Pipeline Execution ↗ for commit ebdd2bc

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	1m 54s	View ↗
`nx run-many --target=build --exclude=examples/**`	✅ Succeeded	1s	View ↗

☁️ Nx Cloud last updated this comment at 2026-10-25 12:07:19 UTC

pkg-pr-new · 2026-10-24T21:03:20Z

More templates

@tanstack/angular-form

npm i https://pkg.pr.new/@tanstack/angular-form@2445

@tanstack/form-core

npm i https://pkg.pr.new/@tanstack/form-core@2445

@tanstack/form-devtools

npm i https://pkg.pr.new/@tanstack/form-devtools@2445

@tanstack/lit-form

npm i https://pkg.pr.new/@tanstack/lit-form@2445

@tanstack/preact-form

npm i https://pkg.pr.new/@tanstack/preact-form@2445

@tanstack/react-form

npm i https://pkg.pr.new/@tanstack/react-form@2445

@tanstack/react-form-devtools

npm i https://pkg.pr.new/@tanstack/react-form-devtools@2445

@tanstack/react-form-nextjs

npm i https://pkg.pr.new/@tanstack/react-form-nextjs@2445

@tanstack/react-form-remix

npm i https://pkg.pr.new/@tanstack/react-form-remix@2445

@tanstack/react-form-start

npm i https://pkg.pr.new/@tanstack/react-form-start@2445

@tanstack/solid-form

npm i https://pkg.pr.new/@tanstack/solid-form@2445

@tanstack/solid-form-devtools

npm i https://pkg.pr.new/@tanstack/solid-form-devtools@2445

@tanstack/svelte-form

npm i https://pkg.pr.new/@tanstack/svelte-form@2445

@tanstack/vue-form

npm i https://pkg.pr.new/@tanstack/vue-form@2445

commit: ebdd2bc

Co-authored-by: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com>

LeCarbonator

LGTM!

LeCarbonator requested changes Oct 24, 2026

View reviewed changes

Comment thread docs/framework/react/guides/reactivity.md Outdated

Comment thread docs/framework/react/guides/reactivity.md

dgesteves and others added 2 commits October 25, 2026 00:49

Update docs/framework/react/guides/reactivity.md

6ef186f

Co-authored-by: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com>

docs(react): recommend useSelector in field components

ebdd2bc

dgesteves requested a review from LeCarbonator October 25, 2026 00:01

LeCarbonator approved these changes Oct 25, 2026

View reviewed changes

LeCarbonator merged commit 12eea6d into TanStack:main Oct 25, 2026
8 of 9 checks passed

Navigation Menu

Repository navigation

docs(react): document field state reactivity - #2445

docs(react): document field state reactivity#2445
LeCarbonator merged 3 commits into
TanStack:mainfrom
dgesteves:docs/react-field-state-reactivity

dgesteves commented Oct 24, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

LeCarbonator left a comment

Uh oh!

Uh oh!

Uh oh!

nx-cloud Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

LeCarbonator left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dgesteves commented Oct 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

coderabbitai Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeCarbonator left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nx-cloud Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeCarbonator left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dgesteves commented Oct 24, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Oct 24, 2026 •

edited

Loading

coderabbitai Bot commented Oct 24, 2026 •

edited

Loading

nx-cloud Bot commented Oct 24, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 24, 2026 •

edited

Loading