Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

Query Status and Fetch Status

Understand status, fetchStatus, isPending, isLoading, isFetching and isPaused in TanStack Query, and learn which flag to use for spinners, banners and offline states.

Beginners often mix up isPending, isLoading and isFetching. The confusion is natural: the library tracks two separate questions about every query, and each has its own field.

  1. status answers: do I have data? (pending, success or error)
  2. fetchStatus answers: is the query function running? (fetching, paused or idle)

They are independent. A query can have data and be fetching (a background refresh). It can be pending and idle (it is disabled, or it is waiting). Once this clicks, the rest of the flags are just shortcuts.

The two axes

stateDiagram-v2
  [*] --> pending
  pending --> success: query fn resolves
  pending --> error: query fn rejects after retries
  success --> success: refetch succeeds
  success --> error: refetch fails after retries
  error --> success: refetch succeeds

status describes the data you hold. It changes only when a fetch finishes.

status Meaning Shortcut
pending No data yet isPending
success Data is available isSuccess
error The last fetch failed isError
fetchStatus Meaning Shortcut
fetching The query function is running (including retries) isFetching
paused Wanted to fetch but is offline isPaused
idle Nothing is running none

The shortcut flags

  • isPending: status === "pending". Use it to decide whether you have anything to show.
  • isFetching: fetchStatus === "fetching". True on the first load and on every background refetch.
  • isLoading: isFetching && isPending. The very first request is in flight. This is the flag for a full-page spinner, because it ignores disabled queries.
  • isRefetching: isFetching && !isPending. A background refresh while data is on screen.
  • isPaused: the query wants to run but there is no network connection.
  • isStale: the data is older than staleTime.
  • isPlaceholderData: the data shown is placeholder, not real (see a later lesson).

Which one to use for common UI:

UI element Flag
Show the content or an "empty" message isSuccess / data
Full-screen first-load spinner isLoading (or isPending)
Small "updating..." indicator in a corner isFetching or isRefetching
Error page isError and no data
Error banner above stale content isError and data !== undefined
"You are offline" notice isPaused

Watching the flags change

This panel prints the flags for a query. Press "Refetch" to see a background refresh (isRefetching), and "Fail next" followed by "Refetch" to see the error state while the old data remains.

Live flags panel

During the first load you see status: pending, fetchStatus: fetching and isLoading: true. After success, a refetch shows status: success with fetchStatus: fetching, so only isRefetching and isFetching are true. After a failed refetch, status becomes error but data still holds the last good value.

Combining flags for a good UI

A robust pattern renders in this order: first load, hard error, then content with optional extras.

JSX
function Todos() {
  const { data, isPending, isError, error, isFetching } = useQuery(todosOptions);

  if (isPending) return <Spinner />;
  if (isError && data === undefined) return <ErrorPage error={error} />;

  return (
    <>
      {isError && <Banner>Could not refresh: {error.message}</Banner>}
      <TodoList todos={data} />
      {isFetching && <TopBarSpinner />}
    </>
  );
}

Here the same isError flag leads to two different screens depending on whether stale data exists.

Paused queries and the network

When the browser is offline, Query does not waste a request. A query that wants to fetch enters fetchStatus: "paused" and resumes when the connection returns. The library tracks connectivity with onlineManager. You can drive it manually, which is useful for testing and for apps that know better than navigator.onLine.

A paused query

At first the query is pending and paused: it has no data and is not running. Press "Go online" and it switches to fetching, then success. This is why you should not rely on isLoading to cover an offline first load: it is false while paused, so check isPending as well when you need a spinner or an offline message.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A query already has data and is refreshing in the background. Which statement is true?

    status stays 'success' because data exists, while fetchStatus is 'fetching'. isLoading requires isPending, so it is false.
  2. 2. What does isLoading equal?

    isLoading is true only for the first request of a query that has no data yet and is actually fetching.
  3. 3. Which fetchStatus means the query wants to fetch but the device is offline?

    paused means the fetch is waiting for the network. 'stale' is not a fetchStatus.
  4. 4. After a failed background refetch of data you already had, what does the result look like?

    The last good data is kept. That is why you can show a banner above stale content.

Summary

  • status says whether you have data (pending, success, error); fetchStatus says whether a request is running (fetching, paused, idle).
  • isLoading = first fetch in flight; isRefetching = background refresh; isFetching = either.
  • A failed refetch keeps the old data, so you can show stale content with an error banner.
  • Offline queries are paused, not failed; onlineManager controls the online signal.

Next: QueryClient and QueryClientProvider