Open History to see the last commit
1---
2id: MutationObserver
3title: MutationObserver
4---
5β
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7β
8Defined in: [packages/query-core/src/mutationObserver.ts:37](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L37)
9β
10Observes a single mutation and derives a `MutationObserverResult` from it.
11A framework hook like `useMutation` creates one `MutationObserver` per hook
12call, keeps it stable across re-renders, calls `setOptions` when the options
13passed to the hook change, subscribes to it to re-render on updates, and
14reads `getCurrentResult()` for the value to return. Calling `mutate()`
15builds a new underlying `Mutation` in the `MutationCache` and executes it.
16β
17## Example
18β
19```ts
20const observer = new MutationObserver(queryClient, {
21 mutationFn: (variables: { title: string }) => addPost(variables),
22})
23```
24β
25## Extends
26β
27- `Subscribable`\<`MutationObserverListener`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>\>
28β
29## Type Parameters
30β
31### TData
32β
33`TData` = `unknown`
34β
35### TError
36β
37`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
38β
39### TVariables
40β
41`TVariables` = `void`
42β
43### TOnMutateResult
44β
45`TOnMutateResult` = `unknown`
46β
47## Constructors
48β
49### Constructor
50β
51```ts
52new MutationObserver<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(client: QueryClient, options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>): MutationObserver<TData, TError, TVariables, TOnMutateResult>;
53```
54β
55Defined in: [packages/query-core/src/mutationObserver.ts:57](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L57)
56β
57#### Parameters
58β
59##### client
60β
61`QueryClient`
62β
63##### options
64β
65[`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
66β
67#### Returns
68β
69`MutationObserver`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
70β
71#### Overrides
72β
73```ts
74Subscribable<
75 MutationObserverListener<TData, TError, TVariables, TOnMutateResult>
76>.constructor
77```
78β
79## Properties
80β
81### options
82β
83```ts
84options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>;
85```
86β
87Defined in: [packages/query-core/src/mutationObserver.ts:45](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L45)
88β
89## Methods
90β
91### getCurrentResult()
92β
93```ts
94getCurrentResult(): MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
95```
96β
97Defined in: [packages/query-core/src/mutationObserver.ts:165](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L165)
98β
99Returns the observer's current result, derived from the observed
100mutation's state (or the default, `idle` state if no mutation has been
101built yet, e.g. before the first `mutate()` call or after `reset()`).
102β
103#### Returns
104β
105[`MutationObserverResult`](../type-aliases/MutationObserverResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
106β
107The observer's latest result.
108β
109***
110β
111### hasListeners()
112β
113```ts
114hasListeners(): boolean;
115```
116β
117Defined in: [packages/query-core/src/subscribable.ts:43](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L43)
118β
119Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
120β
121#### Returns
122β
123`boolean`
124β
125`true` if at least one listener is registered.
126β
127#### Inherited from
128β
129```ts
130Subscribable.hasListeners
131```
132β
133***
134β
135### mutate()
136β
137```ts
138mutate(variables: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>): Promise<TData>;
139```
140β
141Defined in: [packages/query-core/src/mutationObserver.ts:217](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L217)
142β
143Builds a new `Mutation` in the `MutationCache` using the observer's
144current options, detaches this observer from any previously observed
145mutation, attaches it to the new one, and executes it with the given
146variables.
147β
148The optional per-call `options` (`onSuccess`/`onError`/`onSettled`) are
149invoked once the mutation settles, in addition to any callbacks defined
150on the observer's own options.
151β
152#### Parameters
153β
154##### variables
155β
156`TVariables`
157β
158The variables passed to the `mutationFn`.
159β
160##### options?
161β
162[`MutateOptions`](../interfaces/MutateOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
163β
164Per-call `onSuccess`, `onError`, and `onSettled` callbacks.
165β
166#### Returns
167β
168`Promise`\<`TData`\>
169β
170A promise that resolves with the mutation's data, or rejects with its error.
171β
172#### Example
173β
174```ts
175await observer.mutate(
176 { title: 'New post' },
177 { onSuccess: (data) => console.log(data) },
178)
179```
180β
181***
182β
183### reset()
184β
185```ts
186reset(): void;
187```
188β
189Defined in: [packages/query-core/src/mutationObserver.ts:188](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L188)
190β
191Detaches the observer from the mutation it is currently observing (if
192any) and resets the observed result back to its default, `idle` state.
193β
194This does not cancel an in-flight mutation; the mutation itself keeps
195running to completion and its own callbacks still fire, but this
196observer stops reflecting its state and a subsequent `mutate()` call
197will build a brand new mutation.
198β
199#### Returns
200β
201`void`
202β
203#### See
204β
205[MutationObserver#mutate](#mutate)
206β
207#### Example
208β
209```ts
210observer.reset()
211```
212β
213***
214β
215### setOptions()
216β
217```ts
218setOptions(options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>): void;
219```
220β
221Defined in: [packages/query-core/src/mutationObserver.ts:100](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L100)
222β
223Updates the observer's options.
224β
225If the new `mutationKey` differs from the previous one (and both were
226defined), the observer is reset, detaching it from the mutation it was
227observing. Otherwise, if the currently observed mutation is still
228`pending`, its options are updated in place as well.
229β
230#### Parameters
231β
232##### options
233β
234[`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
235β
236The new mutation observer options. They are defaulted with [QueryClient#defaultMutationOptions](QueryClient.md#defaultmutationoptions) before being applied.
237β
238#### Returns
239β
240`void`
241β
242#### Example
243β
244```ts
245observer.setOptions({
246 mutationFn: (variables: { title: string }) => addPost(variables),
247 onSuccess: (data) => console.log(data),
248})
249```
250β
251***
252β
253### subscribe()
254β
255```ts
256subscribe(listener: MutationObserverListener): () => void;
257```
258β
259Defined in: [packages/query-core/src/subscribable.ts:28](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L28)
260β
261Registers a listener to be called on every update this object notifies about. Returns a function
262that removes the listener again β call it to stop listening. The base class never drops a listener
263on its own, though some subclasses clear all of theirs in `destroy()`.
264β
265#### Parameters
266β
267##### listener
268β
269`MutationObserverListener`
270β
271Called on each update, with whatever the subclass passes to its subscribers.
272β
273#### Returns
274β
275A function that removes the listener.
276β
277() => `void`
278β
279#### Example
280β
281```ts
282const unsubscribe = subscribable.subscribe(() => {
283 // react to the update
284})
285β
286unsubscribe()
287```
288β
289#### Inherited from
290β
291```ts
292Subscribable.subscribe
293```