useMutation

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,
  {
    status,
    isIdle,
    isLoading,
    isSuccess,
    isError,
    data,
    error,
    reset
  }
] = useMutation(mutationResolver, {
  onMutate,
  onSuccess,
  onError,
  onSettled,
  throwOnError,
  useErrorBoundary,
})

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

Arguments

• mutationResolver: A Blitz mutation resolver
  • Required
• options
  • Optional

Options

• onMutate: Function(inputArguments) => Promise | snapshotValue
  • 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: Function(data, inputArguments) => Promise | undefined
  • Optional
  • This function will fire when the mutation is successful and will be passed the mutation's result.
  • Fires after the mutate-level onSuccess handler (if it is defined)
  • If a promise is returned, it will be awaited and resolved before proceeding
• onError: Function(err, inputArguments, onMutateValue) => Promise | undefined
  • Optional
  • This function will fire if the mutation encounters an error and will be passed the error.
  • Fires after the mutate-level onError handler (if it is defined)
  • If a promise is returned, it will be awaited and resolved before proceeding
• onSettled: Function(data, error, inputArguments, onMutateValue) => Promise | undefined
  • Optional
  • This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
  • Fires after the mutate-level onSettled handler (if it is defined)
  • If a promise is returned, it will be awaited and resolved before proceeding
• throwOnError
  • Defaults to true
  • Set this to false if failed mutations should not re-throw errors from the mutation function to the mutate function.
• useErrorBoundary
  • Defaults to false, typically you will not use this
  • Set this to true if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary

Returns

[invoke, mutationExtras]

invoke: Function(inputArguments, { onSuccess, onSettled, onError, throwOnError }) => Promise

• The mutation function you can call with inputArguments to trigger the mutation and optionally override the original mutation options.
• inputArguments: any
  • Optional
  • The inputArguments object to pass to the mutationResolver.
• Remaining options extend the same options described above in the useMutation hook.
• Lifecycle callbacks defined here will fire after those of the same type defined in the useMutation-level options.

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 | Any
  • Defaults to undefined
  • The last successfully resolved data for the mutation.
• error: null | Error
  • The error object for the query, if an error was encountered.
• reset: Function() => void
  • A function to clean the mutation internal state (i.e., it resets the mutation to its initial state).