mutations

89 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

Get all variables of running mutations with useMutationState

To get all variables of mutations with pending status, use useMutationState with filters: { status: 'pending' } and select: (mutation) => mutation.state.variables.

useMutationState example: access running mutations

import { useMutationState } from '@tanstack/react-query' const variables = useMutationState({ filters: { status: 'pending' }, select: (mutation) => mutation.state.variables, })

useMutationState return type

useMutationState returns an Array of TResult, where TResult is whatever the select function returns for each matching mutation.

useMutation return value: data property

data is returned from useMutation and defaults to undefined. It contains the last successfully resolved data for the mutation.

useMutation return value: error property

error is returned from useMutation as null | TError. It contains the error object for the mutation if an error was encountered.

useMutation return value: reset function

reset is a function returned from useMutation with signature () => void. It cleans the mutation internal state and resets the mutation to its initial state.

useMutation return value: failureCount property

failureCount is a number property returned from useMutation that tracks the failure count for the mutation. It is incremented every time the mutation fails and reset to 0 when the mutation succeeds.

useMutation return value: failureReason property

failureReason is returned from useMutation as null | TError. It contains the failure reason for the mutation retry and is reset to null when the mutation succeeds.

useMutation onMutate callback

onMutate is an optional callback with signature (variables: TVariables, context: MutationFunctionContext) => Promise<TOnMutateResult | void> | TOnMutateResult | void. It fires before the mutation function executes and receives the same variables the mutation function would receive. It is useful for performing optimistic updates. The value returned from this function is passed to both onError and onSettled in case of mutation failure, allowing you to roll back optimistic updates.

useMutation onSuccess callback

onSuccess is an optional callback with signature (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown. It fires when the mutation is successful and receives the mutation's result data. If a promise is returned, it will be awaited and resolved before proceeding.

useMutation onError callback

onError is an optional callback with signature (err: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown. It fires if the mutation encounters an error and receives the error object. If a promise is returned, it will be awaited and resolved before proceeding.

useMutation onSettled callback

onSettled is an optional callback with signature (data: TData, error: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown. It fires when the mutation is either successfully fetched or encounters an error and receives either the data or error. If a promise is returned, it will be awaited and resolved before proceeding.

useMutation retry parameter

retry parameter controls mutation retry behavior. Defaults to 0 (no retries). If false, failed mutations will not retry. If true, failed mutations will retry infinitely. If set to a number like 3, failed mutations will retry until the failed mutations count reaches that number. Can also be a function with signature (failureCount: number, error: TError) => boolean.

useMutation scope parameter

scope is an optional parameter with shape { id: string }. It defaults to a unique id so that all mutations run in parallel. Mutations with the same scope id will run in serial.

useMutation throwOnError parameter

throwOnError controls whether mutation errors are thrown to error boundaries. If true, errors are thrown in the render phase and propagate to the nearest error boundary. If false, the behavior is disabled. Can also be a function with signature (error: TError) => boolean that returns true to show the error in an error boundary or false to return the error as state.

useMutation meta parameter

meta is an optional Record<string, unknown> parameter that stores additional information on the mutation cache entry. It is accessible wherever the mutation is available, such as in onError and onSuccess functions of the MutationCache.

useMutation return value: mutate function

mutate is a function returned from useMutation with signature (variables: TVariables, { onSuccess, onSettled, onError }) => void. It triggers the mutation with the given variables and optionally accepts callback options. The variables object is optional and is passed to the mutationFn. onSuccess, onError, and onSettled callbacks are optional void functions whose return values are ignored. If multiple requests are made, onSuccess fires only after the latest call.

useMutation return value: mutateAsync function

mutateAsync is returned from useMutation and is similar to mutate but returns a promise which can be awaited. It has the same signature pattern as mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>.

useMutation return value: status property

status is a MutationStatus property returned from useMutation that can be: idle (initial status prior to mutation function executing), pending (mutation is currently executing), error (last mutation attempt resulted in error), or success (last mutation attempt was successful).

useMutation return value: status boolean properties

useMutation returns boolean properties isIdle, isPending, isSuccess, and isError that are derived from the status property.

useMutation return value: isPaused property

isPaused is a boolean property returned from useMutation that is true if the mutation has been paused. See the Network Mode guide for more information.

useMutation QueryClient parameter

useMutation accepts an optional second parameter queryClient?: QueryClient. Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

useMutation return value: variables property

variables is returned from useMutation as undefined | TVariables. It contains the variables object passed to the mutationFn and defaults to undefined.

useMutation hook API overview

The useMutation hook provides a way to perform mutations in React. It accepts options object with mutation configuration, and optionally a QueryClient instance. It returns an object containing state properties and methods like mutate and mutateAsync.

useMutation mutationFn parameter

mutationFn is a required parameter (unless a default mutation function has been defined) that accepts a function with signature (variables: TVariables, context: MutationFunctionContext) => Promise<TData>. It performs an asynchronous task and returns a promise. The context parameter contains a reference to QueryClient, mutationKey, and an optional meta object.

useMutation gcTime parameter

gcTime is a number or Infinity that specifies the time in milliseconds that unused/inactive cache data remains in memory before garbage collection. Defaults to a library-determined value. If set to Infinity, garbage collection is disabled. The maximum allowed time is about 24 days, but this limit can be worked around using timeoutManager.setTimeoutProvider.

useMutation mutationKey parameter

mutationKey is an optional unknown[] array that can be set to inherit defaults set with queryClient.setMutationDefaults.

useMutation networkMode parameter

networkMode is an optional parameter that accepts 'online', 'always', or 'offlineFirst'. It defaults to 'online'. See the Network Mode guide for more information.

useMutation return value: submittedAt property

submittedAt is a number property returned from useMutation representing the timestamp for when the mutation was submitted. It defaults to 0.

Give your agent this brain