status field to distinguish pending vs. loading?

[bdrazen]

Just curious if there was a consideration at any point towards possibly splitting the current pending status into loading and a fourth one denoting the inverse (isPending && !isFetching)? Maybe nascent or something? Had a lot of code throughout a project that relied on the status field passed as a prop to downstream components that I was forced to completely refactor since status alone could no longer reflect isLoading as it did in the original version. At least with two distinct statuses you could cover all bases: status === 'nascent', status === 'loading', ['nascent', 'loading'].includes(status). As it stands, the field has been rendered virtually useless in my project and am not even sure of its intended use case any longer over the boolean flags (isLoading, isPending, etc.).

[abhayclasher]

yo, i feel u. the v5 naming shift from loading to pending tripped up a lot of devs.

tbh the reason they split it is to separate the data state (status) from the network state (fetchStatus).

if u miss the old loading behavior, u basically want isPending && isFetching. query actually exports an isLoading boolean exactly for this (initial fetch with no data yet).

if u really need a single string field for downstream props, u might have to just wrap the hook and derive a custom status like nascent yourself. but sticking to the booleans is usually the 'meta' way now since it handles all the edge cases better. ✌️

[bdrazen]

Yeah, I'm aware of isLoading. Just saying it leads me to basically fully abandon status in favor of those boolean flags across my entire project. I ended up writing a convenience function that returns my suggested breakdown from a QueryResult in cases where I needed a single prop but it's far from ideal. Wondering if some kind of new field (maybe state) that granularizes the pending could be a reasonable addition without breaking compat.

Edit: Wow, just realized v2 actually broke status down in exactly this way with idle but got clobbered together in v4, then renamed in v5. Still kinda wish there were at least a separate field that preserves the original breakdown. Having to either pass down both status and fetchStatus or filter through some custom util is very clunky.

[TkDodo]

the problem with adding this to the main state, as it has been in v3 and v4, is that you get no type narrowing if you check for success and error states, because the idle state (even though unreachable without enabled) is still part of the union.

[bdrazen]

Hmm, not sure I completely follow. Could you maybe clarify with a code example? Currently the type would narrow to pending but isn't that just effectively a composite of what was idle | loading? Unless you mean:

if (status === 'loading') return <Loader />; 
if (status === 'error') return <Error />; 
// could still be idle; data still not guaranteed

Now that would be:

if (status === 'pending') return <Loader />;
if (status === 'error') return <Error />;
// data guaranteed

But the problem here is you wouldn't necessarily want the loader in the pending state unless isLoading === true, which you could code for but then you're effectively just reproducing the old breakdown in a different way.

[TkDodo]

yes, this is the code path I was talking about:

if (status === 'pending') return <Loader />;
if (status === 'error') return <Error />;
// data guaranteed

If you are not using enabled, which is the majority of cases, this is what you’d expect. Yes, if you use enabled, you need to handle that extra case, but that is imo better than forcing everyone else to handle status==='idle' even though they don't use enabled.

[bdrazen]

Fair enough. I understand the reasoning but still wonder if it wouldn't be worth then maybe adding a separate field with the wider breakdown when you need to be able to account for loading without being forced to rearchitect your dependencies for multiple boolean flags.

[x-tahosin]

You can recover the v4 isLoading semantics by combining status with fetchStatus — that split is exactly what v5 did to the old single field, and it's discoverable but not obvious from the migration guide.

The mapping:

v4	v5
status === 'loading' (no data, fetching)	status === 'pending' && fetchStatus === 'fetching' (≡ isLoading)
status === 'loading' (no data, not fetching, e.g. enabled: false)	status === 'pending' && fetchStatus === 'idle'
isFetching while having data	status === 'success' && fetchStatus === 'fetching'

So your "nascent" idea is already there, just in a different field:

const { status, fetchStatus, isLoading, isPending, isFetching } = useQuery(...);

// Hard-no-data-and-actively-loading (the thing you were missing):
const isLoading_v4_compat = status === 'pending' && fetchStatus === 'fetching';
//          ^ identical to `isLoading` from v5's flag, which TanStack added back specifically for this case

A quick look at the source confirms isLoading in v5 is literally derived as status === 'pending' && fetchStatus === 'fetching'. So if you only ever read isLoading (not status), v5 behaves the same as v4 did.

If your refactor pain came from reading status everywhere as a discriminator (switch (status)-style), the migration is one of:

1. Add a derived field to your selector / wrapper that reproduces the 3-state enum:

   const phase: 'loading' | 'idle' | 'fetching' | 'success' | 'error' =
     status === 'pending' && fetchStatus === 'fetching' ? 'loading'
     : status === 'pending' && fetchStatus === 'idle'   ? 'idle'
     : status === 'success' && fetchStatus === 'fetching' ? 'fetching'
     : status; // 'success' | 'error'

2. Use the boolean flags everywhere (isLoading, isPending, isFetching, isError, isSuccess). They're all derived in v5 and cover every combination — status is mostly there for the discriminated-union types, not for direct user logic.

The reason v5 split it: status now strictly reflects "do I have data or not, and if not, is it because of an error" — it never lies about the existence of data. fetchStatus reflects the network layer separately. That's actually closer to what most apps want, but it does require you to check both fields when you used to check one.

Refs:

• v5 migration guide → "loading status changed"
• useQuery reference → status / fetchStatus