API Documentation / @pinia/colada / UseMutationOptions
Interface: UseMutationOptions<TResult, TVars, TError, TContext>
Options to create a mutation.
Extends
Pick<UseMutationOptionsGlobal,"gcTime">
Type Parameters
TResult
TResult = unknown
TVars
TVars = void
TError
TError = ErrorDefault
TContext
TContext extends Record<any, any> = _EmptyObject
Properties
gcTime?
optional gcTime: number | false;Time in ms after which, once the mutation is no longer being used, it will be garbage collected to free resources. Set to false to disable garbage collection (not recommended).
Default
60_000 (1 minute)Inherited from
Pick.gcTimekey?
optional key: _MutationKey<NoInfer<TVars>>;Optional key to identify the mutation globally and access it through other helpers like useMutationState(). If you don't need to reference the mutation elsewhere, you should ignore this option.
mutation()
mutation: (vars, context) => Promise<TResult>;The key of the mutation. If the mutation is successful, it will invalidate the mutation with the same key and refetch it
Parameters
vars
TVars
context
_ReduceContext<NoInfer<TContext>>
Returns
Promise<TResult>
onBeforeMutate()?
optional onBeforeMutate: (vars, context) => _Awaitable<undefined | null | void | TContext>;Runs before the mutation is executed. It should be placed before mutation() for context to be inferred. It can return a value that will be passed to mutation, onSuccess, onError and onSettled. If it returns a promise, it will be awaited before running mutation.
Parameters
vars
NoInfer<TVars>
The variables passed to the mutation.
context
UseMutationGlobalContext
Returns
_Awaitable<undefined | null | void | TContext>
Example
useMutation({
// must appear before `mutation` for `{ foo: string }` to be inferred
// within `mutation`
onBeforeMutate() {
return { foo: 'bar' }
},
mutation: (id: number, { foo }) => {
console.log(foo) // bar
return fetch(`/api/todos/${id}`)
},
onSuccess(context) {
console.log(context.foo) // bar
},
})onError()?
optional onError: (error, vars, context) => unknown;Runs if the mutation encounters an error.
Parameters
error
TError
The error thrown by the mutation.
vars
NoInfer<TVars>
The variables passed to the mutation.
context
The merged context from onBeforeMutate and the global context. Properties returned by onBeforeMutate can be undefined if onBeforeMutate throws.
UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>> | Partial<Record<never, never>> & Partial<Record<keyof _ReduceContext<NoInfer<TContext>>, never>>
Returns
unknown
onMutate()?
optional onMutate: (vars, context) => _Awaitable<undefined | null | void | TContext>;Parameters
vars
NoInfer<TVars>
The variables passed to the mutation.
context
UseMutationGlobalContext
Returns
_Awaitable<undefined | null | void | TContext>
Deprecated
Use onBeforeMutate instead.
onSettled()?
optional onSettled: (data, error, vars, context) => unknown;Runs after the mutation is settled, regardless of the result.
Parameters
data
The result of the mutation. undefined if the mutation failed.
undefined | NoInfer<TResult>
error
The error thrown by the mutation. undefined if the mutation was successful.
undefined | TError
vars
NoInfer<TVars>
The variables passed to the mutation.
context
The merged context from onBeforeMutate and the global context. Properties returned by onBeforeMutate can be undefined if onBeforeMutate throws.
UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>> | Partial<Record<never, never>> & Partial<Record<keyof _ReduceContext<NoInfer<TContext>>, never>>
Returns
unknown
onSuccess()?
optional onSuccess: (data, vars, context) => unknown;Runs if the mutation is successful.
Parameters
data
NoInfer<TResult>
The result of the mutation.
vars
NoInfer<TVars>
The variables passed to the mutation.
context
UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>
The merged context from onBeforeMutate and the global context.
Returns
unknown