useMutation

The useMutation hook is used to mutate data. Best Practices & Guide

import { useMutation } from '@archibald/client';

const RETURN_VALUE = useMutation(PARAMETERS);

tip

Revalidate the mutated data after a mutation with client.invalidate(key) — it refetches stale-while-revalidate (without clearing first), so useFetch/useSuspenseFetch consumers keep their current content instead of flashing a Suspense fallback. See the Best Practices & Guide.

Parameters

Name	Type	Description
options	MutateOptions | undefined	The options that define the behavior of the useMutation hook.

The hook takes no key parameter — a key for the mutation is generated automatically. To use a specific key, set the mutationKey option.

Options

• Type: MutateOptions

The MutateOptions object has the following properties:

Name	Type	Default	Description
after	VoidFunction		A function that will be executed after the mutate function. Receives params of type DataFunctionParams. More Info...
before	VoidFunction		A function that will be executed before the mutate function. Receives params of type DataFunctionParams. More Info...
mutationKey	FetchKey		If defined it sets a special key for that mutation and doesn't use a generated key. More Info...
ttl	number	15 minutes	Defines how long an entry should be kept in the cache. Use -1 for endless caching. More Info...
error	number	5 seconds	Defines how long an error is kept in the cache. More Info...
suspense	boolean	false	Deprecated. Throws the mutation promise during render, which unmounts the form and loses its local state. Drive writes with a transition or <form action> instead. More Info...
errorBoundary	boolean	false	Defines if the error should be thrown. Relies on the deprecated suspense option; prefer { throwOnError: true } on the mutate call inside a transition/error boundary. More Info...
clearKeyAfterMutate	boolean	false	A config to define if the mutation is being cleared directly afterwards. More Info...
enabled	boolean	true	Defines if the useMutation hook is active or not. If this is set to false, the action function will not be executed. More Info...
keepError	boolean	false	Keep error in cache when transitioning between pages. More Info...

Return value

The return object has the following properties:

Property	Type	Description
data	DATA_TYPE | null	The data that was retrieved through the hook. This value can be typed by passing a type to the hook.
error	DefaultResponseError | null	The error that was returned in the action.
isLoading	boolean	Returns true, when the mutation is being executed.
isPending	boolean	Alias of isLoading (React 19 / react-query v5 naming), suitable for transitions and <form action>.
isDone	boolean	Returns true when the mutation is finished.
isSuccess	boolean	Returns true when the mutation finished successfully.
isError	boolean	Returns true when the mutation got an error.
mutate	Function	Executes the provided action and caches the result. Has a stable identity, so it can be passed to <form action={mutate}> or memoized children. Pass { throwOnError: true } per call for a rejecting promise a transition or error boundary can catch.
resetError	Function	Manually clear the error state from the cache and local state. More Info...
mutation	DataMutation	The DataMutation instance.