useMutation

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

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).