useMutation

Parameters

• document: GraphQL document containing the mutation operation. Can also be a function returning the document.

• options: (default: null) Options object. Can also be a function returning an options object.

  • variables: Variables object.

  • awaitRefetchQueries: By default, refetchQueries does not wait for the refetched queries to be completed, before resolving the mutation Promise. This ensures that query refetching does not hold up mutation response handling (query refetching is handled asynchronously). Set awaitRefetchQueries to true if you would like to wait for the refetched queries to complete, before the mutation can be marked as resolved.

  • clientId: Id of the client that should be used for this mutation if you have provided multiple clients.

  • context: The context to be passed to the link execution chain. This context will only be used with the mutation. It will not be used with refetchQueries. Refetched queries use the context they were initialized with (since the intitial context is stored as part of the ObservableQuery instance). If a specific context is needed when refetching queries, make sure it is configured (via the query context option) when the query is first initialized/run.

  • errorPolicy: Specifies the ErrorPolicy to be used for this operation.

    • none
    • all
    • ignore

  • fetchPolicy: Specifies the FetchPolicy to be used for this mutation.

    • network-only: return result from network, fail if network call doesn't succeed, save to cache.
    • no-cache: return result from network, fail if network call doesn't succeed, don't save to cache.

  • optimisticResponse: An object that represents the result of this mutation that will be optimistically stored before the server has actually returned a result. This is most often used for optimistic UI, where we want to be able to see the result of a mutation immediately, and update the UI later if any errors appear.

  • refetchQueries: A list of query names which will be refetched once this mutation has returned. This is often used if you have a set of queries which may be affected by a mutation and will have to update. Rather than writing a mutation query reducer (i.e. updateQueries) for this, you can simply refetch the queries that will be affected and achieve a consistent store once these queries return.

  • update: This function will be called twice over the lifecycle of a mutation. Once at the very beginning if an optimisticResponse was provided. The writes created from the optimistic data will be rolled back before the second time this function is called which is when the mutation has successfully resolved. At that point update will be called with the actual mutation result and those writes will not be rolled back.

    The reason a DataProxy is provided instead of the user calling the methods directly on ApolloClient is that all of the writes are batched together at the end of the update, and it allows for writes generated by optimistic data to be rolled back.

    Note that since this function is intended to be used to update the store, it cannot be used with a no-cache fetch policy. If you're interested in performing some action after a mutation has completed, and you don't need to update the store, use the Promise returned from mutate instead.

  • updateQueries: A MutationQueryReducersMap, which is map from query names to mutation query reducers. Briefly, this map defines how to incorporate the results of the mutation into the results of queries that are currently being watched by your application.

  • throws: 'auto' | 'always' | 'never': By default ('auto'), mutate will throw errors if you don't register an onError callback.

Return

• mutate(variables, overrideOptions): call the mutation with this function.

• loading: boolean Ref tracking the progress of the mutation.

• error: Error Ref holding any occuring error.

• called: boolean Ref holding true if the mutation was already called.

• onDone(handler): Event hook called when the mutation successfully completes. Handler is called with: result (mutation result) and context which is an object with client (ApolloClient instance).

• onError(handler): Event hook called when an error occurs. Handler is called with: error and context which is an object with client (ApolloClient instance).