Application-wide mutation status
Show a global saving or loading indicator whenever any mutation is pending.
TanStack · Hook
useIsMutating
useIsMutating returns the number of currently pending mutations. Optional filters can limit the count, making it useful for application-wide loading indicators.
How it works
Call this hook to subscribe to the number of currently pending mutations. Pass mutation filters to narrow which mutations count, and optionally provide a custom QueryClient; otherwise the nearest context supplies it.
Syntax
function useIsMutating(filters?: MutationFilters<unknown, Error, unknown, unknown>, queryClient?: QueryClient): number;Parameters
| Name | Type | Description |
|---|---|---|
filters | MutationFilters<unknown, Error, unknown, unknown> | Optional filters used to narrow the mutations included in the count; supported fields include exact, mutationKey, predicate, and status. |
queryClient | QueryClient | Optional client used to inspect mutations. If omitted, the nearest context provides it. |
Returns
number — the number of mutations currently pending.
Key points
- It produces a live count of pending mutations rather than a boolean.
- Use the count to drive global saving or loading UI.
- The exact filter option restricts matching to the complete mutation key.
- A predicate filter supports custom matching logic for mutations.
- The status filter can constrain matches to a selected mutation state.
Common mistakes
- A mutationKey filter matches mutations using that key; without exact matching, a posts key can include mutations beneath the posts prefix.
- If the hook must inspect a client other than the one from the nearest context, pass that client explicitly.
Example: Show a mutation indicator
import { useIsMutating } from '@tanstack/react-query'
export function PostsMutatingIndicator() {
const count = useIsMutating({ mutationKey: ['posts'] })
return count > 0 ? <span>Saving posts...</span> : null
}Counts pending mutations whose keys match the posts prefix and displays an indicator while at least one is active.
When to use it
Feature-specific feedback
Display progress feedback only while mutations for a feature key are active.
Custom client monitoring
Observe mutations from a separately configured QueryClient.
Interview questions
QWhat does useIsMutating return?
It returns a number representing currently pending mutations, making it suitable for an app-wide loading indicator. With no filters, the count covers all pending mutations.
Follow-up: How would you count only post mutations? Pass a filter such as { mutationKey: ['posts'] } and use the returned number to control the indicator.
QHow can the mutation count be narrowed?
The first argument is an optional MutationFilters object. It can narrow matches by mutation key, exactness, predicate, or status.
Follow-up: When would exact be useful? Use exact when a key should match only that precise mutation key rather than mutations beneath its key prefix.
QHow does useIsMutating choose a QueryClient?
The optional second argument is a QueryClient. When omitted, the hook uses the QueryClient from the nearest context.
Follow-up: Why pass a client explicitly? This lets the hook observe mutations managed by a particular custom client instead of the contextual default.
Related
useIsMutatinguseMutationuseMutationStateQueryClientMutationFilters