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