Open History to see the last commit
1---
2id: mutationOptions
3title: mutationOptions
4redirect_from:
5 - framework/react/reference/mutationOptions
6---
7β
8## Overview
9β
10```ts
11function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
12function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
13```
14β
15- [`WithRequired<UseMutationOptions>` β `WithRequired<UseMutationOptions>`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`.
16- [`Omit<UseMutationOptions>` β `Omit<UseMutationOptions>`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload β use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`.
17β
18See also: [Parameters](#parameters-summary) Β· [Returns](#returns-summary)
19β
20<a id="call-signature-1"></a>
21β
22## Call Signature
23β
24```ts
25function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
26```
27β
28Defined in: [packages/react-query/src/mutationOptions.ts:31](https://github.com/TanStack/query/blob/main/packages/react-query/src/mutationOptions.ts#L31)
29β
30You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
31`mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
32`useMutationState`.
33β
34### Type Parameters
35β
36#### TData
37β
38`TData` = `unknown`
39β
40#### TError
41β
42`TError` = `Error`
43β
44#### TVariables
45β
46`TVariables` = `void`
47β
48#### TOnMutateResult
49β
50`TOnMutateResult` = `unknown`
51β
52### Parameters
53β
54#### options
55β
56[`WithRequired`](../type-aliases/WithRequired.md)\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
57β
58The mutation options to use, identical to what you'd pass to `useMutation`, with a
59required `mutationKey`.
60β
61### Returns
62β
63[`WithRequired`](../type-aliases/WithRequired.md)\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
64β
65The same options object, unchanged.
66β
67### See
68β
69[useMutation](useMutation.md) to run the mutation these options describe.
70β
71### Example
72β
73Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "savingβ¦" indicator:
74```tsx
75import { mutationOptions, useMutationState } from '@tanstack/react-query'
76β
77const createPostOptions = mutationOptions({
78 mutationKey: ['posts', 'create'],
79 mutationFn: createPost,
80})
81β
82function SavingIndicator() {
83 const isCreatingPost = useMutationState({
84 filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
85 }).length > 0
86β
87 return isCreatingPost ? <span>Savingβ¦</span> : null
88}
89```
90β
91<a id="call-signature-2"></a>
92β
93## Call Signature
94β
95```ts
96function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
97```
98β
99Defined in: [packages/react-query/src/mutationOptions.ts:69](https://github.com/TanStack/query/blob/main/packages/react-query/src/mutationOptions.ts#L69)
100β
101You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
102`mutationKey` is required on this overload β use this when you don't need to target the mutation via a
103`mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
104such as `status`.
105β
106### Type Parameters
107β
108#### TData
109β
110`TData` = `unknown`
111β
112#### TError
113β
114`TError` = `Error`
115β
116#### TVariables
117β
118`TVariables` = `void`
119β
120#### TOnMutateResult
121β
122`TOnMutateResult` = `unknown`
123β
124### Parameters
125β
126#### options
127β
128`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
129β
130The mutation options to use, identical to what you'd pass to `useMutation`, without a
131`mutationKey`.
132β
133### Returns
134β
135`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
136β
137The same options object, unchanged.
138β
139### Remarks
140β
141See the other overload's example for looking a mutation up via `useMutationState`.
142β
143### See
144β
145[useMutation](useMutation.md) to run the mutation these options describe.
146β
147### Example
148β
149```tsx
150import { mutationOptions, useMutation } from '@tanstack/react-query'
151β
152export const createPostOptions = mutationOptions({
153 mutationFn: createPost,
154})
155β
156function CreatePost() {
157 const mutation = useMutation(createPostOptions)
158 return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
159}
160```
161β
162<a id="parameters-summary"></a>
163β
164## Parameters
165β
166### options
167β
168`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
169β
170The mutation options to use, identical to what you'd pass to `useMutation`, without a
171`mutationKey`.
172β
173<a id="options-properties"></a>
174β
175#### `options` properties
176β
177Built from [`UseMutationOptions`](../interfaces/UseMutationOptions.md#properties). See the type above for what it changes.
178β
179<a id="returns-summary"></a>
180β
181## Returns
182β
183`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
184β
185The same options object, unchanged.
186β
187<a id="result-properties"></a>
188β
189### Result properties
190β
191Built from [`UseMutationOptions`](../interfaces/UseMutationOptions.md#properties). See the type above for what it changes.