Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

useMutationState.md

111 lines3.3 KB

1---
2id: useMutationState
3title: useMutationState
4redirect_from:
5 - framework/react/reference/useMutationState
6---
7​
8<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
9​
10```ts
11function useMutationState<TResult = MutationState<unknown, Error, unknown, unknown>, TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>>(options?: MutationStateOptions<TResult, TMutation>, queryClient?: QueryClient): TResult[];
12```
13​
14Defined in: [packages/react-query/src/useMutationState.ts:183](https://github.com/TanStack/query/blob/main/packages/react-query/src/useMutationState.ts#L183)
15​
16`useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
17`filters` ([MutationFilters](../interfaces/MutationFilters.md)) to narrow down your mutations, and `select` to transform the mutation
18state.
19​
20## Type Parameters
21​
22### TResult
23​
24`TResult` = [`MutationState`](../interfaces/MutationState.md)\<`unknown`, `Error`, `unknown`, `unknown`\>
25​
26### TMutation
27​
28`TMutation` *extends* [`Mutation`](../classes/Mutation.md)\<`any`, `any`, `any`, `any`\> = `MutationTypeFromResult`\<`TResult`\>
29​
30## Parameters
31​
32### options?
33​
34`MutationStateOptions`\<`TResult`, `TMutation`\> = `{}`
35​
36The `filters` to narrow down matched mutations, and an optional `select` to transform the
37mutation state.
38​
39### queryClient?
40​
41[`QueryClient`](../classes/QueryClient.md)
42​
43Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
44be used.
45​
46## Returns
47​
48`TResult`[]
49​
50Will be an Array of whatever `select` returns for each matching mutation.
51​
52## Examples
53​
54Get all variables of all running mutations:
55```tsx
56import { useMutationState } from '@tanstack/react-query'
57​
58function PendingPosts() {
59 const pendingVariables = useMutationState({
60 filters: { status: 'pending' },
61 select: (mutation) => mutation.state.variables,
62 })
63​
64 return <>{pendingVariables.length} posts saving...</>
66```
67​
68Get all data for specific mutations via the `mutationKey`:
69```tsx
70import { useMutation, useMutationState } from '@tanstack/react-query'
71​
72const mutationKey = ['posts']
73​
74function Posts() {
75 // Some mutation that we want to get the state for
76 const mutation = useMutation({
77 mutationKey,
78 mutationFn: createPosts,
79 })
80​
81 const savedPosts = useMutationState({
82 // this mutation key needs to match the mutation key of the given mutation (see above)
83 filters: { mutationKey, status: 'success' },
84 select: (mutation) => mutation.state.data,
85 })
86​
87 return (
88 <button onClick={() => mutation.mutate(['New Post'])}>
89 Create post ({savedPosts.length} saved so far)
90 </button>
91 )
93```
94​
95Access the latest successful mutation data via the `mutationKey`. Each invocation of `mutate` adds a new
96entry to the mutation cache for `gcTime` milliseconds β€” with the `status: 'success'` filter below, check the
97last item that `useMutationState` returns to get the latest successful invocation:
98```tsx
99import { useMutationState } from '@tanstack/react-query'
100​
101function LatestPost() {
102 const savedPosts = useMutationState({
103 filters: { mutationKey: ['posts'], status: 'success' },
104 select: (mutation) => mutation.state.data,
105 })
106​
107 const latestSavedPost = savedPosts[savedPosts.length - 1]
108​
109 return <>{latestSavedPost ? 'Saved' : 'Nothing saved yet'}</>
111```