Why do the docs recommend isPending instead of isLoading?

[eddie-dunn]

Under https://tanstack.com/query/v5/docs/react/guides/queries#query-basics the examples given for checking for the query loading state check against isPending. E.g.:

For most queries, it's usually sufficient to check for the isPending state, then the isError state, then finally, assume that the data is available and render the successful state:

As I understand it, the isLoading will accomplish the same thing, with the additional benefit that it also works as users would expect for dependent queries. It was basically the whole reason isInitialLoading was renamed to isLoading in v5, and the v4 version of isLoading was renamed to isPending.

I therefore think involving isPending in the first basic example of how to use queries will just unnecessarily confuse users.

So, why don't the docs recommend isLoading as the default way of checking loading state?

[kalijonn]

I'm not sure what you mean by dependent queries. isLoading would only be true while the first fetch is in flight (in v5).

I think the logic is consistent between v4 and v5. Most of the users expect to use a state that would be set to true whenever the queryFn is running and not just the first fetch. In v4 it was isLoading. In v5, its renamed to isPending.

v5 isPending === v4 isLoading
v5 isLoading === v4 isInitialLoading

I'm just a fellow consumer of the library and cannot possibly know what most of the users want. All I'm saying is that the docs are consistent between v4 and v5.

[eddie-dunn]

You must be confused, you're not addressing my question at all.

I'm not sure what you mean by dependent queries.

Dependent queries are functionally the same as what's also referred to as lazy queries in the docs.

[TkDodo]

So, why don't the docs recommend isLoading as the default way of checking loading state?

Because isPending is directly derived from the status field, while isLoading is a combined state of status and fetchStatus. Therefore, there is no guarantee that checking for isLoading and isError will result in "data is now guaranteed to be available". You'll only get that by checking isPending, and TypeScript will also only remove undefined from the union if you've checked for pending and error.

[eddie-dunn]

That's an excellent blog post, but it doesn't address my concern that a guide called "Query Basics" recommends checking what I perceive as a worse "loading" flag, for the reasons stated above. It's a n00b trap.

If you check for isLoading, you theoretically have to always check for "what if I'm pending but not loading?"

That's the whole point, though? isLoading is useful if we don't care about pending state because a query might or might not be disabled. I cannot personally think of a reason where I would want to check pending over loading state, so that seems more like the exception to the rule.

[TkDodo]

the introduction page hasn't changed, it's been the same for the last 1.5 years. We've just renamed a flag, and now it's more obvious what it does.

I can guarantee that if we change it to check for isLoading, lots of people will ask why it doesn't type-narrow data. It has happened before.

It's fine if you don't like it, but it's not a trap.

[eddie-dunn]

That is fair, and while I don't agree with the trade-off being made here, I do get your point. Thanks for clarifying. 🙏

[Donhv]

Can you guys give me an example fetch real api isLoading different value with isPending @TkDodo

[TkDodo]

useQuery({ queryKey, queryFn, enabled: false })

there you go, isPending: true, isLoading: false

[armanrozika]

That's an excellent blog post, but it doesn't address my concern that a guide called "Query Basics" recommends checking what I perceive as a worse "loading" flag, for the reasons stated above. It's a n00b trap.

If you check for isLoading, you theoretically have to always check for "what if I'm pending but not loading?"

That's the whole point, though? isLoading is useful if we don't care about pending state because a query might or might not be disabled. I cannot personally think of a reason where I would want to check pending over loading state, so that seems more like the exception to the rule.

I am that n00b that get trapped with the isPending haha. Glad I found this discussion tho

[FDiskas]

It is still funny
https://arc.net/l/quote/wbzyunbk

• isPending or status === 'pending' - The mutation is currently running

So it is pending or running?

[TkDodo]

both. a Promise can be in 3 states: pending, fulfilled or rejected. In context of a mutation, once you initiate it by calling mutate or mutateAsync, the status is “pending”, because you are “waiting” for the promise to resolve. So in that sense, the mutation is also “running”.

[w90]

Renaming the most used flag in react-query = great idea for us people migrating from v4 to v5

[TkDodo]

the mistake happened in v4, sorry about that. v5 tries to mitigate it by bringing back how v3 worked. I agree it's a bit messy but mistakes were made and instead of sticking to a bad approach, we decided to revert it and implement the solution that we should've done with v4.

[w90]

No worries, it turned out to be only 1 hour refactor in our small codebase, so it's not that bad ;)
Keep up the marvelous work guys. You rock!

[chiptus]

I wish there was a fix to v4. I'm just migrating to v4 (Can't to v5 because we're blocked with upgrade to react v18), and it seems so crazy to change and then revert once we upgrade

[canadaduane]

@chiptus A technique you can use is called "corruption isolation" or "anti-corruption layer". The idea would be to wrap the useQuery function with your own useQuery function, and then call your own function rather than tanstack function. This way, within your own definition of the function, you can change certain aspects of it to work exactly as your codebase expects, without being subject to external dependencies' changes.