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