feat: Update isLoading behaviour (#4888)

* ♻️ Add isPending and update isLoading behaviour

* ✅ Fix useQuery tests

* ✅ Fix query core tests

* ✅ Fix react-query tests

* ♻️ Update mutation to use isPending

* ♻️ Mark isInitialLoading as deprecated

* ✅ Fix query core mutation tests

* ✅ Fix persist query tests

* ✅ Fix solid query tests

* ✅ Fix all vue query tests

* 📝 isLoading -> isPending wherever necessary

* 📝 Use `pending` for `loading` and remove references for `isInitialLoading`

* 📝 Use `pending` for `loading` and remove references for `isInitialLoading`

* 📝 Update upgrade guide

* 👌 Review updates

* ✨ Updated examples to use isPending

* Update docs/react/reference/useQuery.md

---------

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: prateek3255

docs/react/adapters/react-query.md

@@ -16,7 +16,7 @@ function Example() {
 
   return (
     <div>
-      {query.isLoading
+      {query.isPending
         ? 'Loading...'
         : query.isError
         ? 'Error!'

docs/react/adapters/solid-query.md

@@ -21,7 +21,7 @@ function Example() {
   return (
     <div>
       <Switch>
-        <Match when={query.isLoading}>
+        <Match when={query.isPending}>
           <p>Loading...</p>
         </Match>
         <Match when={query.isError}>
@@ -126,7 +126,7 @@ export default function App() {
 
 function Example() {
   // ❌ react version -- supports destructing outside reactive context
-  // const { isLoading, error, data } = useQuery({
+  // const { isPending, error, data } = useQuery({
   //   queryKey: ['repoData'], () =>
   //   queryFn: fetch('https://api.github.com/repos/tannerlinsley/react-query').then(res =>
   //     res.json()
@@ -145,7 +145,7 @@ function Example() {
   // ✅ access query properties in JSX reactive context
   return (
     <Switch>
-      <Match when={query.isLoading}>Loading...</Match>
+      <Match when={query.isPending}>Loading...</Match>
       <Match when={query.isError}>Error: {query.error.message}</Match>
       <Match when={query.isSuccess}>
         <div>
@@ -190,7 +190,7 @@ function Example() {
   return (
     <div>
       <Switch>
-        <Match when={query.isLoading}>
+        <Match when={query.isPending}>
           <p>Loading...</p>
         </Match>
         <Match when={query.isError}>

docs/react/adapters/vue-query.md

@@ -20,7 +20,7 @@ import { useQueryClient, useQuery, useMutation } from "@tanstack/vue-query";
 const queryClient = useQueryClient();
 
 // Query
-const { isLoading, isError, data, error } = useQuery({ queryKey: ['todos'], queryFn: getTodos });
+const { isPending, isError, data, error } = useQuery({ queryKey: ['todos'], queryFn: getTodos });
 
 // Mutation
 const mutation = useMutation({
@@ -40,7 +40,7 @@ function onButtonClick() {
 </script>
 
 <template>
-  <span v-if="isLoading">Loading...</span>
+  <span v-if="isPending">Loading...</span>
   <span v-else-if="isError">Error: {{ error.message }}</span>
   <!-- We can assume by this point that `isSuccess === true` -->
   <ul v-else>

docs/react/community/tkdodos-blog.md

@@ -19,7 +19,7 @@ TanStack Query maintainer [TkDodo](https://twitter.com/tkdodo) has a series of b
 
 ## [#4: Status Checks in React Query](https://tkdodo.eu/blog/status-checks-in-react-query)
 
-> We usually check for `isLoading` first before checking for `isError` , but sometimes, checking if `data` is available should be the first thing to do. This article shows how the wrong status check order can negatively impact user experience. [Read more...](https://tkdodo.eu/blog/status-checks-in-react-query)
+> We usually check for `isPending` first before checking for `isError` , but sometimes, checking if `data` is available should be the first thing to do. This article shows how the wrong status check order can negatively impact user experience. [Read more...](https://tkdodo.eu/blog/status-checks-in-react-query)
 
 ## [#5: Testing React Query](https://tkdodo.eu/blog/testing-react-query)
 

docs/react/guides/background-fetching-indicators.md

@@ -3,7 +3,7 @@ id: background-fetching-indicators
 title: Background Fetching Indicators
 ---
 
-A query's `status === 'loading'` state is sufficient enough to show the initial hard-loading state for a query, but sometimes you may want to display an additional indicator that a query is refetching in the background. To do this, queries also supply you with an `isFetching` boolean that you can use to show that it's in a fetching state, regardless of the state of the `status` variable:
+A query's `status === 'pending'` state is sufficient enough to show the initial hard-loading state for a query, but sometimes you may want to display an additional indicator that a query is refetching in the background. To do this, queries also supply you with an `isFetching` boolean that you can use to show that it's in a fetching state, regardless of the state of the `status` variable:
 
 [//]: # 'Example'
 
@@ -19,7 +19,7 @@ function Todos() {
     queryFn: fetchTodos,
   })
 
-  return status === 'loading' ? (
+  return status === 'pending' ? (
     <span>Loading...</span>
   ) : status === 'error' ? (
     <span>Error: {error.message}</span>

docs/react/guides/caching.md

@@ -23,7 +23,7 @@ Let's assume we are using the default `gcTime` of **5 minutes** and the default
 - A second instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts elsewhere.
   - Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache.
   - The new instance triggers a new network request using its query function.
-    - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/useQuery) are updated (including `isFetching`, `isLoading`, and other related values) because they have the same query key.
+    - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/useQuery) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key.
   - When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data.
 - Both instances of the `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` query are unmounted and no longer in use.
   - Since there are no more active instances of this query, a garbage collection timeout is set using `gcTime` to delete and garbage collect the query (defaults to **5 minutes**).

docs/react/guides/dependent-queries.md

@@ -34,20 +34,23 @@ const {
 The `projects` query will start in:
 
 ```tsx
-status: 'loading'
+status: 'pending'
+isLoading: false
 fetchStatus: 'idle'
 ```
 
 As soon as the `user` is available, the `projects` query will be `enabled` and will then transition to:
 
 ```tsx
-status: 'loading'
+status: 'pending'
+isLoading: true
 fetchStatus: 'fetching'
 ```
 
 Once we have the projects, it will go to:
 
 ```tsx
 status: 'success'
+isLoading: false
 fetchStatus: 'idle'
 ```

docs/react/guides/disabling-queries.md

@@ -8,7 +8,7 @@ If you ever want to disable a query from automatically running, you can use the
 When `enabled` is `false`:
 
 - If the query has cached data, then the query will be initialized in the `status === 'success'` or `isSuccess` state.
-- If the query does not have cached data, then the query will start in the `status === 'loading'` and `fetchStatus === 'idle'` state.
+- If the query does not have cached data, then the query will start in the `status === 'pending'` and `fetchStatus === 'idle'` state.
 - The query will not automatically fetch on mount.
 - The query will not automatically refetch in the background.
 - The query will ignore query client `invalidateQueries` and `refetchQueries` calls that would normally result in the query refetching.
@@ -18,7 +18,7 @@ When `enabled` is `false`:
 
 ```tsx
 function Todos() {
-  const { isInitialLoading, isError, data, error, refetch, isFetching } =
+  const { isLoading, isError, data, error, refetch, isFetching } =
     useQuery({
       queryKey: ['todos'],
       queryFn: fetchTodoList,
@@ -39,7 +39,7 @@ function Todos() {
         </>
       ) : isError ? (
         <span>Error: {error.message}</span>
-      ) : isInitialLoading ? (
+      ) : isLoading ? (
         <span>Loading...</span>
       ) : (
         <span>Not ready ...</span>
@@ -84,12 +84,12 @@ function Todos() {
 
 [//]: # 'Example2'
 
-### isInitialLoading
+### isLoading (Previously: `isInitialLoading`)
 
-Lazy queries will be in `status: 'loading'` right from the start because `loading` means that there is no data yet. This is technically true, however, since we are not currently fetching any data (as the query is not _enabled_), it also means you likely cannot use this flag to show a loading spinner.
+Lazy queries will be in `status: 'pending'` right from the start because `pending` means that there is no data yet. This is technically true, however, since we are not currently fetching any data (as the query is not _enabled_), it also means you likely cannot use this flag to show a loading spinner.
 
-If you are using disabled or lazy queries, you can use the `isInitialLoading` flag instead. It's a derived flag that is computed from:
+If you are using disabled or lazy queries, you can use the `isLoading` flag instead. It's a derived flag that is computed from:
 
-`isLoading && isFetching`
+`isPending && isFetching`
 
 so it will only be true if the query is currently fetching for the first time.

docs/react/guides/infinite-queries.md

@@ -66,7 +66,7 @@ function Projects() {
     getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
   })
 
-  return status === 'loading' ? (
+  return status === 'pending' ? (
     <p>Loading...</p>
   ) : status === 'error' ? (
     <p>Error: {error.message}</p>

docs/react/guides/migrating-to-v5.md

@@ -298,4 +298,14 @@ The `Hydrate` component has been renamed to `HydrationBoundary`. The `Hydrate` c
 + </HydrationBoundary>
 ```
 
+### `status: loading` has been changed to `status: pending` and `isLoading` has been changed to `isPending` and `isInitialLoading` has now been renamed to `isLoading`
+
+The `loading` status has been renamed to `pending`, and similarly the derived `isLoading` flag has been renamed to `isPending`.
+
+For mutations as well the `status` has been changed from `loading` to `pending` and the `isLoading` flag has been changed to `isPending`.
+
+Lastly the a new derived `isLoading` flag has been added to the queries that is implemented as `isPending && isFetching`. This means that `isLoading` and `isInitialLoading` have the same thing, but `isInitialLoading` is deprecated now and will be removed in the next major version.
+
+To understand the reasoning behing this change checkout the [v5 roadmap discussion](https://github.com/TanStack/query/discussions/4252).
+
 [//]: # 'FrameworkBreakingChanges'