🚀Announcing Flightcontrol - Optimized Deployment for Fullstack Blitz.js and Next.js 🚀
Back to Documentation Menu

useMutation

Topics

Jump to a Topic

Example

import {useMutation} from 'blitz'
import updateProject from 'app/projects/mutations/updateProject'

function (props) {
  const [updateProjectMutation] = useMutation(updateProject)

  return (
    <Formik
      onSubmit={async values => {
        try {
          const project = await updateProjectMutation(values)
        } catch (error) {
          alert('Error saving project')
        }
      }}>
      {/* ... */}
    </Formik>
  )
}

For more examples and use cases, see the mutation usage documentation.

API

const [
  invoke,
  {
    data,
    error,
    isError,
    isIdle,
    isLoading,
    isPaused,
    isSuccess,
    mutate,
    reset,
    status,
  },
] = useMutation(mutationResolver, {
  mutationKey,
  onError,
  onMutate,
  onSettled,
  onSuccess,
  useErrorBoundary,
})

const promise = invoke(inputArguments, {
  onError,
  onSettled,
  onSuccess,
})

Arguments

Options

  • 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<void> | 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<void> | 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<void> | 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: boolean
    • Optional
    • Defaults to the global query config's useErrorBoundary value, which is false
    • Set this to true if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary

Returns

[mutate, mutationExtras]

mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
  • 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.
mutationExtras: Object
  • 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).

Idea for improving this page? Edit it on GitHub.