useMutation

1 const {
2   data,
3   error,
4   isError,
5   isIdle,
6   isLoading,
7   isPaused,
8   isSuccess,
9   mutate,
10   mutateAsync,
11   reset,
12   status,
13 } = useMutation(mutationFn, {
14   cacheTime,
15   mutationKey,
16   onError,
17   onMutate,
18   onSettled,
19   onSuccess,
20   useErrorBoundary,
21   meta
22 })
23 
24 mutate(variables, {
25   onError,
26   onSettled,
27   onSuccess,
28 })

Options

• mutationFn: (variables: TVariables) => Promise<TData>
  • Required
  • A function that performs an asynchronous task and returns a promise.
  • variables is an object that mutate will pass to your mutationFn
• cacheTime: number | Infinity
  • The time in milliseconds that unused/inactive cache data remains in memory. When a mutation's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different cache times are specified, the longest one will be used.
  • If set to Infinity, will disable garbage collection
• mutationKey: string
  • Optional
  • A mutation key can be set to inherit defaults set with queryClient.setMutationDefaults or to identify the mutation in the devtools.
• onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void
  • Optional
  • This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
  • Useful to perform optimistic updates to a resource in hopes that the mutation succeeds
  • The value returned from this function will be passed to both the onError and onSettled functions in the event of a mutation failure and can be useful for rolling back optimistic updates.
• onSuccess: (data: TData, variables: TVariables, context?: TContext) => Promise<unknown> | void
  • Optional
  • This function will fire when the mutation is successful and will be passed the mutation's result.
  • If a promise is returned, it will be awaited and resolved before proceeding
• onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | void
  • Optional
  • This function will fire if the mutation encounters an error and will be passed the error.
  • If a promise is returned, it will be awaited and resolved before proceeding
• onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | void
  • Optional
  • This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
  • If a promise is returned, it will be awaited and resolved before proceeding
• retry: boolean | number | (failureCount: number, error: TError) => boolean
  • If false, failed mutations will not retry by default.
  • If true, failed mutations will retry infinitely.
  • If set to an number, e.g. 3, failed mutations will retry until the failed mutations count meets that number.
• retryDelay: number | (retryAttempt: number, error: TError) => number
  • This function receives a retryAttempt integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
  • A function like attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) applies exponential backoff.
  • A function like attempt => attempt * 1000 applies linear backoff.
• useErrorBoundary: undefined | boolean | (error: TError) => boolean
  • Defaults to the global query config's useErrorBoundary value, which is undefined
  • Set this to true if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary
  • Set this to false to disable the behavior of throwing errors to the error boundary.
  • If set to a function, it will be passed the error and should return a boolean indicating whether to show the error in an error boundary (true) or return the error as state (false)
• meta: Record<string, unknown>
  • Optional
  • If set, stores additional information on the mutation cache entry that can be used as needed. It will be accessible wherever the mutation is available (eg. onError, onSuccess functions of the MutationCache).

Returns

• mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void
  • The mutation function you can call with variables to trigger the mutation and optionally override options passed to useMutation.
  • variables: TVariables
    • Optional
    • The variables object to pass to the mutationFn.
  • Remaining options extend the same options described above in the useMutation hook.
  • If you make multiple requests, onSuccess will fire only after the latest call you've made.
• mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
  • Similar to mutate but returns a promise which can be awaited.
• status: string
  • Will be:
    • idle initial status prior to the mutation function executing.
    • loading if the mutation is currently executing.
    • error if the last mutation attempt resulted in an error.
    • success if the last mutation attempt was successful.
• isIdle, isLoading, isSuccess, isError: boolean variables derived from status
• data: undefined | unknown
  • Defaults to undefined
  • The last successfully resolved data for the query.
• error: null | TError
  • The error object for the query, if an error was encountered.
• reset: () => void
  • A function to clean the mutation internal state (i.e., it resets the mutation to its initial state).