0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-16 22:50:20 +00:00
query/docs/framework/react/reference/functions/mutationOptions.md
Wonsuk Choi 4c568a28c8
docs(react-query): generate reference docs with TypeDoc (#11366)
* docs(vue-query,solid-query): inline react reference content instead of 'ref'-ing hand-written react docs

* docs(react-query): generate reference docs with TypeDoc

* docs(vue-query,solid-query): fix dangling suspense-hook links left over from the react content copy

* docs(solid-query): apply solid's callback call form to inlined reference examples

* docs(react-query): correct inaccurate JSDoc statements flagged in review

* docs(vue-query,solid-query): fix reactivity-aware examples and inaccurate type signatures flagged in review

* docs(vue-query,solid-query): fix remaining type/behavior inaccuracies flagged in second review

* docs(react-query): stop implying a default queryFn defers a fetch the way 'enabled: false' does

* docs(vue-query): mark 'mutate'/'mutateAsync' per-call options as optional
2026-09-02 16:06:54 +09:00

3.7 KiB

id title
mutationOptions mutationOptions

Call Signature

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

Defined in: react-query/src/mutationOptions.ts:33

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

Defined in: react-query/src/mutationOptions.ts:74

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 look the mutation up later (e.g. with useMutationState).

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.

See

useMutation to run the mutation these options describe.

Remarks

Without a mutationKey, the mutation can't be targeted via a mutationKey filter in useMutationState — it can still be observed through other filters, such as status — see the other overload's example for that.

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