fix(react-query): do not report isFetching when subscribed is false

[LeSingh1]

Fixes #10718.

When useQuery or useQueries is called with subscribed: false, the observer never subscribes to the query and no fetch is triggered. However, useBaseQuery and useQueries were unconditionally setting _optimisticResults to 'optimistic', which makes QueryObserver.createResult flip fetchStatus to 'fetching' whenever shouldFetchOnMount returns true. The result was an inconsistent state where the returned object reported isFetching: true and fetchStatus: 'fetching' while the underlying query stayed at fetchStatus: 'idle' and queryFn was never called. This is exactly the pattern documented for React Native, where consumers toggle subscribed to pause queries on unfocused screens, so the inconsistency was easy to hit and confusing to debug.

The fix is small. In both useBaseQuery and useQueries, when options.subscribed === false, we skip the optimistic fetching state and leave _optimisticResults undefined so that the observer returns the actual cache state. The isRestoring branch is unchanged. Once subscribed flips back to true on a later render, the optimistic state kicks back in as before, so re-subscribe behavior is unaffected.

A regression test has been added under the existing subscribed describe block in useQuery.test.tsx. It renders a query with subscribed: false, checks that every recorded state has isFetching: false and fetchStatus: 'idle', and asserts that queryFn is never called. I confirmed the test fails on main and passes with the fix. The full @tanstack/react-query and @tanstack/query-core vitest suites pass locally, type checks are clean, and a patch changeset is included.

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Fixed incorrect status reporting for unsubscribed queries, ensuring they correctly display as idle when no fetch is active.

• Tests

  • Added test coverage for query status behavior when subscriptions are disabled.

[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: 8309d140-8b68-4852-807a-3f0e9af6a53f

📥 Commits

Reviewing files that changed from the base of the PR and between 48b7d66 and 13f6d29.

📒 Files selected for processing (4)

• .changeset/fix-subscribed-isfetching.md
• packages/react-query/src/__tests__/useQuery.test.tsx
• packages/react-query/src/useBaseQuery.ts
• packages/react-query/src/useQueries.ts

---

📝 Walkthrough

Walkthrough

This PR fixes an inconsistency where useQuery and useQueries reported isFetching: true when subscribed: false even though no network request was executing. The fix prevents the optimistic fetching state from being applied when the observer will not subscribe, ensuring reported states remain consistent with the query cache.

Changes

Fix inconsistent fetching state for non-subscribed observers

Layer / File(s)	Summary
Optimistic results state when subscribed: false packages/react-query/src/useBaseQuery.ts, packages/react-query/src/useQueries.ts, .changeset/fix-subscribed-isfetching.md	useBaseQuery and useQueries now set _optimisticResults to undefined when options.subscribed === false, preventing optimistic fetching state from being reported for non-subscribing observers. When restoring or subscribing normally, the prior behavior ('isRestoring' or 'optimistic') is retained.
Test coverage for subscribed: false behavior packages/react-query/src/__tests__/useQuery.test.tsx	A new test verifies that with subscribed: false and no active fetch, queryFn is never called and isFetching and fetchStatus remain at their initial false and idle states respectively.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 When subscribed's false, why fetch with cheer?
No listener's near, the state rings clear—
isFetching rests at calm and true,
Optimistic dreams won't lead us through! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main fix: preventing isFetching from being reported when subscribed is false.
Description check	✅ Passed	The description comprehensively explains the bug, root cause, solution, and testing approach, covering all key aspects expected in the template's changes section.
Linked Issues check	✅ Passed	The PR fully addresses issue #10718 by fixing the inconsistency where isFetching/fetchStatus report fetching when subscribed is false, adding a regression test, and maintaining backward compatibility.
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing the reported issue: modified useBaseQuery.ts and useQueries.ts logic, added regression test, and created changeset documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}