--- id: MutationObserver title: MutationObserver --- Defined in: [packages/query-core/src/mutationObserver.ts:38](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L38) Observes a single mutation and derives a `MutationObserverResult` from it. A framework hook like `useMutation` creates one `MutationObserver` per hook call, keeps it stable across re-renders, calls `setOptions` when the options passed to the hook change, subscribes to it to re-render on updates, and reads `getCurrentResult()` for the value to return. Calling `mutate()` builds a new underlying `Mutation` in the `MutationCache` and executes it. ## Example ```ts const observer = new MutationObserver(queryClient, { mutationFn: (variables: { title: string }) => addPost(variables), }) ``` ## Extends - `Subscribable`\<`MutationObserverListener`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>\> ## Type Parameters ### TData `TData` = `unknown` ### TError `TError` = [`DefaultError`](../type-aliases/DefaultError.md) ### TVariables `TVariables` = `void` ### TOnMutateResult `TOnMutateResult` = `unknown` ## Constructors ### Constructor ```ts new MutationObserver(client, options): MutationObserver; ``` Defined in: [packages/query-core/src/mutationObserver.ts:58](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L58) #### Parameters ##### client [`QueryClient`](QueryClient.md) ##### options [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Returns `MutationObserver`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Overrides ```ts Subscribable< MutationObserverListener >.constructor ``` ## Properties ### listeners ```ts protected listeners: Set>; ``` Defined in: [packages/query-core/src/subscribable.ts:2](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L2) #### Inherited from ```ts Subscribable.listeners ``` *** ### options ```ts options: MutationObserverOptions; ``` Defined in: [packages/query-core/src/mutationObserver.ts:46](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L46) ## Methods ### bindMethods() ```ts protected bindMethods(): void; ``` Defined in: [packages/query-core/src/mutationObserver.ts:75](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L75) #### Returns `void` *** ### getCurrentResult() ```ts getCurrentResult(): MutationObserverResult; ``` Defined in: [packages/query-core/src/mutationObserver.ts:155](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L155) Returns the observer's current result, derived from the observed mutation's state (or the default, `idle` state if no mutation has been built yet, e.g. before the first `mutate()` call or after `reset()`). #### Returns [`MutationObserverResult`](../type-aliases/MutationObserverResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> *** ### hasListeners() ```ts hasListeners(): boolean; ``` Defined in: [packages/query-core/src/subscribable.ts:19](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L19) #### Returns `boolean` #### Inherited from ```ts Subscribable.hasListeners ``` *** ### mutate() ```ts mutate(variables, options?): Promise; ``` Defined in: [packages/query-core/src/mutationObserver.ts:207](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L207) Builds a new `Mutation` in the `MutationCache` using the observer's current options, detaches this observer from any previously observed mutation, attaches it to the new one, and executes it with the given variables. The optional per-call `options` (`onSuccess`/`onError`/`onSettled`) are invoked once the mutation settles, in addition to any callbacks defined on the observer's own options. #### Parameters ##### variables `TVariables` ##### options? [`MutateOptions`](../interfaces/MutateOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Returns `Promise`\<`TData`\> #### Example ```ts await observer.mutate( { title: 'New post' }, { onSuccess: (data) => console.log(data) }, ) ``` *** ### onSubscribe() ```ts protected onSubscribe(): void; ``` Defined in: [packages/query-core/src/mutationObserver.ts:127](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L127) #### Returns `void` #### Overrides ```ts Subscribable.onSubscribe ``` *** ### onUnsubscribe() ```ts protected onUnsubscribe(): void; ``` Defined in: [packages/query-core/src/mutationObserver.ts:135](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L135) #### Returns `void` #### Overrides ```ts Subscribable.onUnsubscribe ``` *** ### reset() ```ts reset(): void; ``` Defined in: [packages/query-core/src/mutationObserver.ts:180](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L180) Detaches the observer from the mutation it is currently observing (if any) and resets the observed result back to its default, `idle` state. This does not cancel an in-flight mutation; the mutation itself keeps running to completion and its own callbacks still fire, but this observer stops reflecting its state and a subsequent `mutate()` call will build a brand new mutation. #### Returns `void` #### Example ```ts observer.reset() ``` #### See [MutationObserver#mutate](#mutate) *** ### setOptions() ```ts setOptions(options): void; ``` Defined in: [packages/query-core/src/mutationObserver.ts:96](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationObserver.ts#L96) Updates the observer's options. If the new `mutationKey` differs from the previous one (and both were defined), the observer is reset, detaching it from the mutation it was observing. Otherwise, if the currently observed mutation is still `pending`, its options are updated in place as well. #### Parameters ##### options [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Returns `void` #### Example ```ts observer.setOptions({ mutationFn: (variables: { title: string }) => addPost(variables), onSuccess: (data) => console.log(data), }) ``` *** ### subscribe() ```ts subscribe(listener): () => void; ``` Defined in: [packages/query-core/src/subscribable.ts:8](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L8) #### Parameters ##### listener `MutationObserverListener` #### Returns ```ts (): void; ``` ##### Returns `void` #### Inherited from ```ts Subscribable.subscribe ```