API Documentation / @pinia/colada / UseMutationOptions

Interface: UseMutationOptions<TData, TVars, TError, TContext>

Options to create a mutation.

Extends

• Pick<UseMutationOptionsGlobal, "gcTime">

Type Parameters

TData

TData = 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.gcTime

---

key?

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<TData>;

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<TData>

---

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 onMutate and the global context. Properties returned by onMutate can be undefined if onMutate 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>;

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`
  onMutate() {
    return { foo: 'bar' }
  },
  mutation: (id: number, { foo }) => {
    console.log(foo) // bar
    return fetch(`/api/todos/${id}`)
  },
  onSuccess(context) {
    console.log(context.foo) // bar
  },
})

---

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<TData>

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 onMutate and the global context. Properties returned by onMutate can be undefined if onMutate 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<TData>

The result of the mutation.

vars

NoInfer<TVars>

The variables passed to the mutation.

context

UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>

The merged context from onMutate and the global context.

Returns

unknown