Global loading indicator
Show a site-wide progress or loading element whenever any query is active in the background.
TanStack · Hook
useIsFetching
useIsFetching returns how many queries are currently loading or fetching in the background. Optional query filters let you count only selected queries, making it useful for global or scoped loading indicators.
How it works
useIsFetching subscribes to the query cache and returns the current number of queries that are loading or fetching in the background. Pass query filters to narrow which queries contribute to the count, or provide a QueryClient when the nearest context is not the intended client.
Syntax
function useIsFetching(filters?: QueryFilters<readonly unknown[]>, queryClient?: QueryClient): number;Parameters
| Name | Type | Description |
|---|---|---|
filters | QueryFilters<readonly unknown[]> | Optional QueryFilters used to narrow the matched queries. Supported filter properties include exact, fetchStatus, predicate, queryKey, stale, and type. |
queryClient | QueryClient | Optional explicit QueryClient. If omitted, the client from the nearest context is used. |
Returns
number — the number of queries currently loading or fetching in the background.
Key points
- The result is a live count, making the hook suitable for application-wide activity indicators.
- Use it when loading state should reflect background activity across multiple components.
- A queryKey filter narrows the count to queries associated with the supplied key or prefix.
- Set exact in the filters when prefix-style query-key matching is too broad.
- fetchStatus filtering lets you include only queries in a selected fetching state, such as fetching or paused.
- A predicate filter supports custom query-selection logic when key and status filters are insufficient.
Common mistakes
- Filters are optional; without them, the count includes every matching fetching query rather than only a particular query family.
- When using a non-default client, pass it explicitly so the hook observes the intended cache.
Example: Global fetching indicator
import { useIsFetching } from '@tanstack/react-query'
export function GlobalLoadingIndicator() {
const isFetching = useIsFetching()
return isFetching > 0 ? (
<div>Queries are fetching in the background...</div>
) : null
}Counts all currently fetching queries and renders a global indicator while the count is positive.
When to use it
Feature-scoped indicator
Display activity only while queries whose keys begin with a feature prefix are fetching.
Predicate-based monitoring
Count only queries satisfying custom selection rules.
Interview questions
QWhat does useIsFetching return?
It returns a number representing how many queries are currently loading or fetching in the background. A component can use whether that number is greater than zero to show a global loading indicator.
Follow-up: How would you limit the indicator to post queries? Pass a queryKey filter such as { queryKey: ['posts'] }; matching filters narrow the counted queries.
QHow can the returned count be narrowed?
The optional filters are QueryFilters. They can narrow matches by properties such as queryKey, exact, fetchStatus, predicate, stale, and type.
Follow-up: How do you require an exact key match? Set exact to true in the filter object instead of relying on prefix matching.
QHow does useIsFetching choose its QueryClient?
The hook accepts an optional QueryClient after the filters. If it is omitted, the client from the nearest context is used.
Follow-up: Why pass a client explicitly? It lets the component track fetching activity in a selected cache when multiple clients are available.
Related
QueryFiltersQueryClientuseIsMutatinguseQuery