useMutation
useMutation
​
Hook used to execute a mutation in a React component.
import type {FeedbackLikeMutation} from 'FeedbackLikeMutation.graphql';
const React = require('React');
const {graphql, useMutation} = require('react-relay');
function LikeButton() {
const [commit, isInFlight] = useMutation<FeedbackLikeMutation>(graphql`
mutation FeedbackLikeMutation($input: FeedbackLikeData!) {
feedback_like(data: $input) {
feedback {
id
viewer_does_like
like_count
}
}
}
`);
if (isInFlight) {
return <Spinner />;
}
return (
<button
onClick={() => {
commit({
variables: {
input: {
id: '123',
text: 'text',
},
},
onCompleted(data) {
console.log(data);
},
});
}}
/>
);
}
Arguments​
mutation
: GraphQL mutation specified using agraphql
template literal.
commitMutationFn
:<T: MutationParameters>(IEnvironment, MutationConfig<T>): Disposable
. [Optional] A function with the same signature ascommitMutation
, which will be called in its stead. Defaults tocommitMutation
.
Flow Type Parameters​
TMutation
: Type parameter that should corresponds the Flow type for the mutation query. This type is available to import from the the auto-generated file:<mutationName>.graphql.js
.
Return Value​
Tuple containing the following values:
- [0]
commitMutation
: The function that will execute the mutation- Arguments, the syntax signature is almost the same as our
commitMutation
APIvariables
: Object containing the variables needed for the mutation. For example, if the mutation defines an$input
variable, this object should contain aninput
key, whose shape must match the shape of the data expected by the mutation as defined by the GraphQL schema.onCompleted
: Callback function executed when the request is completed and the in-memory Relay store is updated with theupdater
function. Takes aresponse
object, which is the "raw" server response. Internallyerrors
are not allowed,CRITICAL
error will be thrown in theonError
handler.onError
: Callback function executed if Relay encounters an error during the request. Internally,CRITICAL
error during reading the mutation result on the serveroptimisticResponse
: Object containing the data to optimistically update the local in-memory store, i.e. immediately, before the mutation request has completed. This object must have the same shape as the mutation's response type, as defined by the GraphQL schema. If provided, Relay will use theoptimisticResponse
data to update the fields on the relevant records in the local data store, beforeoptimisticUpdater
is executed. If an error occurs during the mutation request, the optimistic update will be rolled back.optimisticUpdater
: Function used to optimistically update the local in-memory store, i.e. immediately, before the mutation request has completed. If an error occurs during the mutation request, the optimistic update will be rolled back. This function takes astore
, which is a proxy of the in-memory Relay Store. In this function, the client defines how to update the local data via thestore
instance. For details on how to use thestore
, please refer to our Relay Store API Reference. Please note:- It is usually preferable to just pass an
optimisticResponse
option instead of anoptimisticUpdater
, unless you need to perform updates on the local records that are more complicated than just updating fields (e.g. deleting records or adding items to collections). - If you do decide to use an
optimisticUpdater
, often times it can be the same function asupdater
.
- It is usually preferable to just pass an
updater
: Function used to update the local in-memory store based on the real server response from the mutation. Ifupdater
is not provided, by default, Relay will know to automatically update the fields on the records referenced in the mutation response; however, you should pass anupdater
if you need to make more complicated updates than just updating fields (e.g. deleting records or adding items to collections). When the server response comes back, Relay first reverts any changes introduced byoptimisticUpdater
oroptimisticResponse
and will then executeupdater
. This function takes astore
, which is a proxy of the in-memory Relay Store. In this function, the client defines how to update the local data based on the server response via thestore
instance. For details on how to use thestore
, please refer to our Relay Store API- No environment argument:
useMutation
will automatically use the current environment provided byRelayEnvironmentProvider
- Return value:
disposable
: Object containing adispose
function. Callingdisposable.dispose()
will revert the optimistic update, and Relay won't update the store or call any success/error callback, but the network request is not guaranteed to be cancelled. If thedispose
is called after the mutation has succeeded, it will not rollback the update in Relay store.
- Arguments, the syntax signature is almost the same as our
- [1]
areMutationsInFlight
: Will betrue
if any mutation triggered by callingcommitMutation
is still in flight. If you callcommitMutation
multiple times, there can be multiple mutations in flight at once.
Is this page useful?
Help us make the site even better by answering a few quick questions.