Open History to see the last commit
1---
2id: useMutation
3title: useMutation
4---
5β
6```tsx
7const {
8 data,
9 error,
10 isError,
11 isIdle,
12 isPending,
13 isPaused,
14 isSuccess,
15 failureCount,
16 failureReason,
17 mutate,
18 mutateAsync,
19 reset,
20 status,
21 submittedAt,
22 variables,
23} = useMutation({
24 mutationFn,
25 gcTime,
26 mutationKey,
27 networkMode,
28 onError,
29 onMutate,
30 onSettled,
31 onSuccess,
32 retry,
33 retryDelay,
34 throwOnError,
35 meta,
36})
37β
38mutate(variables, {
39 onError,
40 onSettled,
41 onSuccess,
42})
43```
44β
45**Options**
46β
47- `mutationFn: (variables: TVariables) => Promise<TData>`
48 - **Required, but only if no default mutation function has been defined**
49 - A function that performs an asynchronous task and returns a promise.
50 - `variables` is an object that `mutate` will pass to your `mutationFn`
51- `gcTime: number | Infinity`
52 - The time in milliseconds that unused/inactive cache data remains in memory. When a mutation's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different cache times are specified, the longest one will be used.
53 - If set to `Infinity`, will disable garbage collection
54- `mutationKey: unknown[]`
55 - Optional
56 - A mutation key can be set to inherit defaults set with `queryClient.setMutationDefaults`.
57- `networkMode: 'online' | 'always' | 'offlineFirst`
58 - Optional
59 - defaults to `'online'`
60 - see [Network Mode](./guides/network-mode) for more information.
61- `onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void`
62 - Optional
63 - This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
64 - Useful to perform optimistic updates to a resource in hopes that the mutation succeeds
65 - The value returned from this function will be passed to both the `onError` and `onSettled` functions in the event of a mutation failure and can be useful for rolling back optimistic updates.
66- `onSuccess: (data: TData, variables: TVariables, context: TContext) => Promise<unknown> | unknown`
67 - Optional
68 - This function will fire when the mutation is successful and will be passed the mutation's result.
69 - If a promise is returned, it will be awaited and resolved before proceeding
70- `onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown`
71 - Optional
72 - This function will fire if the mutation encounters an error and will be passed the error.
73 - If a promise is returned, it will be awaited and resolved before proceeding
74- `onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown`
75 - Optional
76 - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
77 - If a promise is returned, it will be awaited and resolved before proceeding
78- `retry: boolean | number | (failureCount: number, error: TError) => boolean`
79 - Defaults to `0`.
80 - If `false`, failed mutations will not retry.
81 - If `true`, failed mutations will retry infinitely.
82 - If set to an `number`, e.g. `3`, failed mutations will retry until the failed mutations count meets that number.
83- `retryDelay: number | (retryAttempt: number, error: TError) => number`
84 - This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
85 - A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff.
86 - A function like `attempt => attempt * 1000` applies linear backoff.
87- `throwOnError: undefined | boolean | (error: TError) => boolean`
88 - Defaults to the global query config's `throwOnError` value, which is `undefined`
89 - Set this to `true` if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary
90 - Set this to `false` to disable the behavior of throwing errors to the error boundary.
91 - If set to a function, it will be passed the error and should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`)
92- `meta: Record<string, unknown>`
93 - Optional
94 - If set, stores additional information on the mutation cache entry that can be used as needed. It will be accessible wherever the `mutation` is available (eg. `onError`, `onSuccess` functions of the `MutationCache`).
95- `queryClient?: QueryClient`,
96 - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
97β
98**Returns**
99β
100- `mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void`
101 - The mutation function you can call with variables to trigger the mutation and optionally hooks on additional callback options.
102 - `variables: TVariables`
103 - Optional
104 - The variables object to pass to the `mutationFn`.
105 - `onSuccess: (data: TData, variables: TVariables, context: TContext) => void`
106 - Optional
107 - This function will fire when the mutation is successful and will be passed the mutation's result.
108 - Void function, the returned value will be ignored
109 - `onError: (err: TError, variables: TVariables, context: TContext | undefined) => void`
110 - Optional
111 - This function will fire if the mutation encounters an error and will be passed the error.
112 - Void function, the returned value will be ignored
113 - `onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined) => void`
114 - Optional
115 - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
116 - Void function, the returned value will be ignored
117 - If you make multiple requests, `onSuccess` will fire only after the latest call you've made.
118- `mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>`
119 - Similar to `mutate` but returns a promise which can be awaited.
120- `status: string`
121 - Will be:
122 - `idle` initial status prior to the mutation function executing.
123 - `pending` if the mutation is currently executing.
124 - `error` if the last mutation attempt resulted in an error.
125 - `success` if the last mutation attempt was successful.
126- `isIdle`, `isPending`, `isSuccess`, `isError`: boolean variables derived from `status`
127- `isPaused: boolean`
128 - will be `true` if the mutation has been `paused`
129 - see [Network Mode](./guides/network-mode) for more information.
130- `data: undefined | unknown`
131 - Defaults to `undefined`
132 - The last successfully resolved data for the query.
133- `error: null | TError`
134 - The error object for the query, if an error was encountered.
135- `reset: () => void`
136 - A function to clean the mutation internal state (i.e., it resets the mutation to its initial state).
137- `failureCount: number`
138 - The failure count for the mutation.
139 - Incremented every time the mutation fails.
140 - Reset to `0` when the mutation succeeds.
141- `failureReason: null | TError`
142 - The failure reason for the mutation retry.
143 - Reset to `null` when the mutation succeeds.
144- `submittedAt: number`
145 - The timestamp for when the mutation was submitted.
146 - Defaults to `0`.
147- `variables: undefined | TVariables`
148 - The `variables` object passed to the `mutationFn`.
149 - Defaults to `undefined`.