mutationOptions

Overview

function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;

• WithRequired<UseMutationOptions> → WithRequired<UseMutationOptions>: You can generally pass everything to mutationOptions that you can also pass to useMutation. A mutationKey is required on this overload so the mutation can be looked up later, e.g. with useMutationState.
• Omit<UseMutationOptions> → Omit<UseMutationOptions>: You can generally pass everything to mutationOptions that you can also pass to useMutation. No mutationKey is required on this overload — use this when you don't need to target the mutation via a mutationKey filter later (e.g. with useMutationState); it can still be observed through other filters, such as status.

See also: Parameters · Returns

Call Signature

function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;

Defined in: packages/react-query/src/mutationOptions.ts:31

You can generally pass everything to mutationOptions that you can also pass to useMutation. A mutationKey is required on this overload so the mutation can be looked up later, e.g. with useMutationState.

Type Parameters

TData

TData = unknown

TError

TError = Error

TVariables

TVariables = void

TOnMutateResult

TOnMutateResult = unknown

Parameters

options

WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The mutation options to use, identical to what you'd pass to useMutation, with a required mutationKey.

Returns

WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The same options object, unchanged.

See

useMutation to run the mutation these options describe.

Example

Looking the mutation up elsewhere via its mutationKey, e.g. for a global "saving…" indicator:

import { mutationOptions, useMutationState } from '@tanstack/react-query'

const createPostOptions = mutationOptions({
  mutationKey: ['posts', 'create'],
  mutationFn: createPost,
})

function SavingIndicator() {
  const isCreatingPost = useMutationState({
    filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
  }).length > 0

  return isCreatingPost ? <span>Saving…</span> : null
}

Call Signature

function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options: Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;

Defined in: packages/react-query/src/mutationOptions.ts:69

You can generally pass everything to mutationOptions that you can also pass to useMutation. No mutationKey is required on this overload — use this when you don't need to target the mutation via a mutationKey filter later (e.g. with useMutationState); it can still be observed through other filters, such as status.

Type Parameters

TData

TData = unknown

TError

TError = Error

TVariables

TVariables = void

TOnMutateResult

TOnMutateResult = unknown

Parameters

options

Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The mutation options to use, identical to what you'd pass to useMutation, without a mutationKey.

Returns

Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The same options object, unchanged.

Remarks

See the other overload's example for looking a mutation up via useMutationState.

See

useMutation to run the mutation these options describe.

Example

import { mutationOptions, useMutation } from '@tanstack/react-query'

export const createPostOptions = mutationOptions({
  mutationFn: createPost,
})

function CreatePost() {
  const mutation = useMutation(createPostOptions)
  return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
}

Parameters

options

Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The mutation options to use, identical to what you'd pass to useMutation, without a mutationKey.

options properties

Built from UseMutationOptions. See the type above for what it changes.

Returns

Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The same options object, unchanged.

Result properties

Built from UseMutationOptions. See the type above for what it changes.