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

useMutationState.md

109 lines3.2 KB

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