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/useMutationState.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

2.8 KiB

id title
useMutationState useMutationState
function useMutationState<TResult, TMutation>(options, queryClient?): TResult[];

Defined in: react-query/src/useMutationState.ts:157

useMutationState is a hook that gives you access to all mutations in the MutationCache. You can pass filters (MutationFilters) to narrow down your mutations, and select to transform the mutation state.

Type Parameters

TResult

TResult = MutationState<unknown, Error, unknown, unknown>

TMutation

TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>

Parameters

options

MutationStateOptions<TResult, TMutation> = {}

The filters to narrow down matched mutations, and an optional select to transform the mutation state.

queryClient?

QueryClient

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns

TResult[]

Will be an Array of whatever select returns for each matching mutation.

Examples

Get all variables of all running mutations:

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

function PendingPosts() {
  const pendingVariables = useMutationState({
    filters: { status: 'pending' },
    select: (mutation) => mutation.state.variables,
  })

  return <>{pendingVariables.length} posts saving...</>
}

Get all data for specific mutations via the mutationKey:

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

const mutationKey = ['posts']

function Posts() {
  // Some mutation that we want to get the state for
  const mutation = useMutation({
    mutationKey,
    mutationFn: createPosts,
  })

  const savedPosts = useMutationState({
    // this mutation key needs to match the mutation key of the given mutation (see above)
    filters: { mutationKey, status: 'success' },
    select: (mutation) => mutation.state.data,
  })

  return (
    <button onClick={() => mutation.mutate(['New Post'])}>
      Create post ({savedPosts.length} saved so far)
    </button>
  )
}

Access the latest mutation data via the mutationKey. Each invocation of mutate adds a new entry to the mutation cache for gcTime milliseconds — check the last item that useMutationState returns to get the latest invocation:

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

function LatestPost() {
  const savedPosts = useMutationState({
    filters: { mutationKey: ['posts'], status: 'success' },
    select: (mutation) => mutation.state.data,
  })

  const latestSavedPost = savedPosts[savedPosts.length - 1]

  return <>{latestSavedPost ? 'Saved' : 'Nothing saved yet'}</>
}