feat: add isRefetching flag

which indicates that a query is fetching, but not loading; useful for background loading spinners that you don't want to display on initial loading because you have a big loading spinner there

Author: TkDodo

docs/src/pages/reference/useQuery.md

@@ -20,6 +20,7 @@ const {
   isPlaceholderData,
   isPreviousData,
   isRefetchError,
+  isRefetching,
   isStale,
   isSuccess,
   refetch,
@@ -218,6 +219,9 @@ const result = useQuery({
 - `isFetching: boolean`
   - Is `true` whenever a request is in-flight, which includes initial `loading` as well as background refetches.
   - Will be `true` if the query is currently fetching, including background fetching.
+- `isRefetching: boolean`
+  - Is `true` whenever a background refetch is in-flight, which _does not_ include initial `loading`
+  - Is the same as `isFetching && !isLoading`
 - `failureCount: number`
   - The failure count for the query.
   - Incremented every time the query fails.

src/core/queryObserver.ts

@@ -553,6 +553,7 @@ export class QueryObserver<
         state.dataUpdateCount > queryInitialState.dataUpdateCount ||
         state.errorUpdateCount > queryInitialState.errorUpdateCount,
       isFetching,
+      isRefetching: isFetching && status !== 'loading',
       isLoadingError: status === 'error' && state.dataUpdatedAt === 0,
       isPlaceholderData,
       isPreviousData,

src/core/types.ts

@@ -279,6 +279,7 @@ export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
   isPlaceholderData: boolean
   isPreviousData: boolean
   isRefetchError: boolean
+  isRefetching: boolean
   isStale: boolean
   isSuccess: boolean
   refetch: (

src/react/tests/useInfiniteQuery.test.tsx

@@ -87,6 +87,7 @@ describe('useInfiniteQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: false,
       refetch: expect.any(Function),
@@ -116,6 +117,7 @@ describe('useInfiniteQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: true,
       refetch: expect.any(Function),

src/react/tests/useQuery.test.tsx

@@ -178,6 +178,7 @@ describe('useQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: false,
       refetch: expect.any(Function),
@@ -201,6 +202,7 @@ describe('useQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: true,
       refetch: expect.any(Function),
@@ -254,6 +256,7 @@ describe('useQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: false,
       refetch: expect.any(Function),
@@ -277,6 +280,7 @@ describe('useQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: false,
       refetch: expect.any(Function),
@@ -300,6 +304,7 @@ describe('useQuery', () => {
       isPlaceholderData: false,
       isPreviousData: false,
       isRefetchError: false,
+      isRefetching: false,
       isStale: true,
       isSuccess: false,
       refetch: expect.any(Function),
@@ -819,6 +824,7 @@ describe('useQuery', () => {
           'data',
           'isFetching',
           'isLoading',
+          'isRefetching',
           'isSuccess',
           'status',
         ],
@@ -1155,24 +1161,28 @@ describe('useQuery', () => {
     expect(states[0]).toMatchObject({
       data: undefined,
       isFetching: true,
+      isRefetching: false,
       isSuccess: false,
       isStale: true,
     })
     expect(states[1]).toMatchObject({
       data: 1,
       isFetching: false,
+      isRefetching: false,
       isSuccess: true,
       isStale: false,
     })
     expect(states[2]).toMatchObject({
       data: 1,
       isFetching: true,
+      isRefetching: true,
       isSuccess: true,
       isStale: true,
     })
     expect(states[3]).toMatchObject({
       data: 2,
       isFetching: false,
+      isRefetching: false,
       isSuccess: true,
       isStale: false,
     })