Aggregate pending work
A dashboard needs to show how many mutations are currently pending across components.
TanStack · Hook
useMutationState
A React hook for reading state from mutations in the MutationCache. Filter matching mutations and optionally map each one to a custom value.
How it works
useMutationState subscribes to matching entries in the MutationCache. Supply filters to choose mutations and optionally select to map each match; without a custom client, it uses the QueryClient from the nearest context, and returns the selected values as an array.
Syntax
function useMutationState<TResult, TMutation>(options?: MutationStateOptions<TResult, TMutation>, queryClient?: QueryClient): TResult[];Parameters
| Name | Type | Description |
|---|---|---|
options? | MutationStateOptions<TResult, TMutation> | Filters mutations and optionally selects a value from each matching mutation. |
queryClient? | QueryClient | Uses this explicitly supplied client; otherwise the nearest context supplies the client. |
Returns
TResult[] — an array containing the selected value for each matching mutation; without select, the mutation state is returned.
Key points
- It observes mutation entries held by the MutationCache, including mutations initiated outside the component using the hook.
- Use MutationFilters such as status or mutationKey to reduce the mutations included in the result.
- The select callback projects every matching mutation into a value suitable for the consuming component.
- The result is an array containing one selected value per matching mutation.
- A shared mutationKey can identify a particular mutation group when reading its state.
Common mistakes
- When filtering by mutationKey, the key must match the key configured on the mutation; otherwise the mutation is not selected.
- If a custom QueryClient is not passed, the hook resolves the client from the nearest context.
Example: Read pending mutation variables
import { useMutation, useMutationState } from '@tanstack/react-query'
function PendingPosts() {
const pendingVariables = useMutationState({
filters: { status: 'pending' },
select: (mutation) => mutation.state.variables,
})
return <>{pendingVariables.length} posts saving...</>
}
export function Posts() {
const mutation = useMutation({
mutationKey: ['posts'],
mutationFn: async (titles: string[]) =>
fetch('/api/posts', {
method: 'POST',
body: JSON.stringify(titles),
}),
})
return <button onClick={() => mutation.mutate(['New Post'])}>Save</button>
}Reads variables from every currently pending mutation, allowing a separate component to display aggregate mutation state.
When to use it
Cross-component mutation state
An optimistic UI needs variables or results from mutations launched by another component.
Read keyed mutation results
A screen needs successful data belonging to one mutation family.
Interview questions
QWhat problem does useMutationState solve?
It exposes all mutations in the MutationCache as an array. MutationFilters narrow the set, while select maps each matching mutation to the value returned by the hook.
Follow-up: How can a component observe mutations started elsewhere? Give the mutations a shared mutationKey, then filter by that key and a status such as pending.
QHow do filters and select work together?
The filters property selects which mutations are included, and select transforms each matching mutation. If select is omitted, the mutation state is returned for each match.
Follow-up: How would you obtain only successful results for one mutation family? Filter with both the shared mutationKey and status: 'success', then select mutation.state.data.
QHow does the hook choose its QueryClient?
The queryClient argument lets the hook use an explicitly supplied QueryClient. When omitted, the nearest context provides the client.
Follow-up: Why might an application pass a client explicitly? To read from a particular QueryClient rather than the one resolved from context.
Related
MutationStateOptionsMutationFiltersQueryClientuseMutationMutationCache