---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/reference/api/@getenginex/sdk-react/functions/useEnginexMutation.md
---
[Reference](../../../index.md) / [@getenginex/sdk-react](../index.md) / useEnginexMutation

# useEnginexMutation()

> **useEnginexMutation**<`I`, `R`, `TOnMutateResult`>(`options`, `overrides?`): `UseMutationResult`<`R`, [`EnginexError`](../../sdk/classes/EnginexError.md), `I`, `TOnMutateResult`>

TanStack `useMutation` over the options of an SDK mutation, with the error typed as
`EnginexError`. On success it invalidates exactly the keys of `invalidates(input, result)`, **waits for the
refetches to finish** and only then calls the app's `onSuccess` (in `overrides`): `mutateAsync` and
`isPending` end up with the data already updated. On error it invalidates nothing and the app's `onError`
receives the `EnginexError`. An app `onSuccess` that throws does not prevent the invalidation (it has
already happened) and moves the mutation to the error state, as in TanStack; in that case `onError` and `error`
receive the error it threw, which is **not** necessarily an `EnginexError` (the
`EnginexError` type describes the failures of `mutationFn`).

`overrides` with an `undefined` value are ignored, and the options' `mutationFn` cannot be replaced.
`TOnMutateResult` is the return of `onMutate`, delivered typed to `onSuccess`, `onError` and `onSettled`.

The `Idempotency-Key` is kept **per hook instance**: it survives a re-render (the options are
recreated on every render) and TanStack's `retry`, and is only reused for the same method and the same
content after an ambiguous failure (network, timeout, 5xx, `KEY_IN_USE` or `VALIDATION_ERROR` after a
2xx). Two hook instances never share a key. Pass the adjustments in `overrides`: spreading the
options (`{ ...m.deposits.createPix(), retry: 1 }`) loses the SDK call and, with it, the per-instance
attempt. Options without the SDK call (a synthetic mutation) use their own `mutationFn`. The options'
`gcTime` (`0` on mutations with credentials) is kept.

## Type Parameters

### I

`I`

### R

`R`

### TOnMutateResult

`TOnMutateResult` = `unknown`

## Parameters

### options

[`EnginexMutationOptions`](../../sdk/query/interfaces/EnginexMutationOptions.md)<`I`, `R`>

Options of a mutation (`m.deposits.createPix()`).

### overrides?

`Omit`<`UseMutationOptions`<`R`, [`EnginexError`](../../sdk/classes/EnginexError.md), `I`, `TOnMutateResult`>, `"mutationFn"`>

`useMutation` options (`onSuccess`, `onError`, `retry`...); not `mutationFn`.

## Returns

`UseMutationResult`<`R`, [`EnginexError`](../../sdk/classes/EnginexError.md), `I`, `TOnMutateResult`>

The `useMutation` result, with `error` typed as `EnginexError`.

## Throws

If called outside an `EnginexProvider` (or a `QueryClientProvider`).

## Example

```ts
const m = useEnginexMutations()
const pix = useEnginexMutation(m.deposits.createPix(), {
  onSuccess: (deposit) => router.push(`/deposito/${deposit.id}`),
})
pix.mutate({ amount: 5000 })
```
