fix(form-core): apply async defaultValues to untouched fields after other fields are edited

[xianjianlf2]

Problem

FormApi.update() gated its defaultValues merge on the form-level isTouched flag (shouldUpdateValues = ... && !this.state.isTouched). Form-level isTouched becomes true as soon as any single field is edited, so once the user touched one field, asynchronously-arriving defaultValues were no longer applied to any field — untouched fields stayed empty.

This makes it impossible to render a form that is usable while part of its default data is still loading: editing one field permanently blocks the async defaults for the others.

Fixes #2229.

Fix

Drop the form-level gate and merge values per-field instead:

• Touched fields keep the user's edited value.
• Untouched fields — including ones that have not mounted yet — receive their newly-arrived default values.

This preserves the existing "don't wipe an edited field on update" behavior (still covered by the existing test) while letting untouched fields update.

Tests

Added form-core regression tests covering both a text field and an array field: after editing one field and then calling update() with new async defaultValues, the untouched field now receives its default while the edited field keeps the user's value. Both fail on main and pass with this change. Full form-core and react-form suites pass; typecheck/lint clean.

Summary by CodeRabbit

• Bug Fixes
  • Updated default values now apply to untouched fields, even after another field has been edited.
  • User-entered values remain preserved for fields that have already been modified.
  • Improved handling for asynchronously loaded defaults, including array fields.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9ac410ec-c7c0-496e-83c1-1422503ec1fd

📥 Commits

Reviewing files that changed from the base of the PR and between 5d11281 and f336dad.

📒 Files selected for processing (3)

• .changeset/async-default-untouched-fields.md
• packages/form-core/src/FormApi.ts
• packages/form-core/tests/FormApi.spec.ts

---

📝 Walkthrough

Walkthrough

FormApi.update now merges incoming default values with current values, preserving touched fields while updating untouched fields. Tests cover scalar and array defaults, and a patch changeset documents the fix.

Changes

Async default value updates

Layer / File(s)	Summary
Preserve edits during default updates packages/form-core/src/FormApi.ts, .changeset/async-default-untouched-fields.md	FormApi.update applies changed defaults to untouched fields while retaining current values for touched fields.
Validate scalar and array defaults packages/form-core/tests/FormApi.spec.ts	Tests verify that scalar and array defaults update correctly without overwriting edited values.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• TanStack/form#2190: Both changes address async defaultValues updates, including array-field update behavior.

Suggested reviewers: crutchcorn

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is informative, but it does not follow the required template sections for Changes, Checklist, and Release Impact.	Rewrite the description using the repository template: add 🎯 Changes, ✅ Checklist, and 🚀 Release Impact sections with the requested details.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the core fix: async defaultValues now apply to untouched fields after edits.
Linked Issues check	✅ Passed	The code and tests satisfy #2229 by merging async defaults per field and preserving edited values.
Out of Scope Changes check	✅ Passed	The changes stay within the issue scope: implementation fix, regression tests, and a changeset entry.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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