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).
Idea for improving this page?Edit it on GitHub