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

mutationOptions.md

191 lines6.4 KB

1---
2id: mutationOptions
3title: mutationOptions
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8## Overview
9​
10```ts
11function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
12function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(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 = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
26```
27​
28Defined in: [packages/preact-query/src/mutationOptions.ts:32](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L32)
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/preact-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
89```
90​
91<a id="call-signature-2"></a>
92​
93## Call Signature
94​
95```ts
96function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
97```
98​
99Defined in: [packages/preact-query/src/mutationOptions.ts:70](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L70)
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/preact-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>
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.