Usage
useMutation allows you to use a mutation factory (via createMutation) within the scope of a React component.
Mutations's allow you to update the state of a query and have built in support for Suspense and Error Boundaries with no extra effort.
When utilizing the invalidate option, a query will automagically update once the mutation has resolved. Combing this with onMutate/setQueryData will create optimistic updates in the UI.
Using Mutations
To use a mutation call the mutate method from the return Object.
Data
The data property contains the returned value of the mutation. This is not necessary for UI updates as mutations were designed to update querys on your behalf through invalidation.
Status
The status property is the lifecycle state associated with the mutation. To learn more about mutation lifecycles, see the create mutation docs.
API
useMutation accepts the following options:
| Params | Required | Description |
|---|---|---|
MutationTuple | Yes | The value of the defined mutation factory. |
Return
useMutation returns and Object with the following options:
| Property | Type | Description |
|---|---|---|
mutate | (variables: V) => Promise<T> | A function that calls the defined mutation Promise. |
status | MutationStatus | The Promise-based status state of the mutation. |
data | T | undefined | The cached state of the query associated with it. |
error | unknown | undefined | The error thrown from the mutation. |