Mutations

Now that we've learned how to fetch data from our backend with Apollo Client, the natural next step is to learn how to update that data with mutations. This article demonstrates how to send updates to your GraphQL server with the useMutation hook. You'll also learn how to update the Apollo Client cache after executing a mutation, and how to track loading and error states for a mutation.

Prerequisites

This article assumes you're familiar with building basic GraphQL mutations. If you need a refresher, we recommend that you read this guide.

This article also assumes that you've already set up Apollo Client and have wrapped your React app in an ApolloProvider component. Read our getting started guide if you need help with either of those steps.

To follow along with the examples below, open up our starter project and sample GraphQL server on CodeSandbox. You can view the completed version of the app here.

Executing a mutation

The useMutation React hook is the primary API for executing mutations in an Apollo application. To run a mutation, you first call useMutation within a React component and pass it a GraphQL string that represents the mutation. When your component renders, useMutation returns a tuple that includes:

• A mutate function that you can call at any time to execute the mutation

• An object with fields that represent the current status of the mutation's execution

Let's look at an example. First, we'll create a GraphQL mutation named ADD_TODO, which represents adding an item to a to-do list. Remember to wrap GraphQL strings in the gql function to parse them into query documents:

1import gql from 'graphql-tag';
2import { useMutation } from '@apollo/react-hooks';
3
4const ADD_TODO = gql`
5  mutation AddTodo($type: String!) {
6    addTodo(type: $type) {
7      id
8      type
9    }
10  }
11`;
12

1import gql from 'graphql-tag';
2import { Mutation } from '@apollo/react-components';
3
4const ADD_TODO = gql`
5  mutation AddTodo($type: String!) {
6    addTodo(type: $type) {
7      id
8      type
9    }
10  }
11`;

Next, we'll create a component named AddTodo that represents the submission form for the to-do list. Inside it, we'll pass our ADD_TODO mutation to the useMutation hook:

1function AddTodo() {
2  let input;
3  const [addTodo, { data }] = useMutation(ADD_TODO);
4
5  return (
6    <div>
7      <form
8        onSubmit={e => {
9          e.preventDefault();
10          addTodo({ variables: { type: input.value } });
11          input.value = '';
12        }}
13      >
14        <input
15          ref={node => {
16            input = node;
17          }}
18        />
19        <button type="submit">Add Todo</button>
20      </form>
21    </div>
22  );
23}

1const AddTodo = () => {
2  let input;
3
4  return (
5    <Mutation mutation={ADD_TODO}>
6      {(addTodo, { data }) => (
7        <div>
8          <form
9            onSubmit={e => {
10              e.preventDefault();
11              addTodo({ variables: { type: input.value } });
12              input.value = '';
13            }}
14          >
15            <input
16              ref={node => {
17                input = node;
18              }}
19            />
20            <button type="submit">Add Todo</button>
21          </form>
22        </div>
23      )}
24    </Mutation>
25  );
26};

Calling the mutate function

The useMutation hook does not automatically execute the mutation you pass it when the component renders. Instead, it returns a tuple with a mutate function in its first position (which we assign to addTodo in the example above). You then call the mutate function at any time to instruct Apollo Client to execute the mutation. In the example above, we call addTodo when the user submits the form.

Providing options

Both useMutation itself and the mutate function accept options that are described in the API reference. Any options you provide to a mutate function override corresponding options you previously provided to useMutation. In the example above, we provide the variables option to addTodo, which enables us to specify any GraphQL variables that the mutation requires.

Tracking mutation status

In addition to a mutate function, the useMutation hook returns an object that represents the current state of the mutation's execution. The fields of this object (fully documented in the API reference) include booleans that indicate whether the mutate function has been called yet, and whether the mutation's result is currently loading.

Updating the cache after a mutation

When you execute a mutation, you modify back-end data. If that data is also present in your Apollo Client cache, you might need to update your cache to reflect the result of the mutation. This depends on whether the mutation updates a single existing entity.

Updating a single existing entity

If a mutation updates a single existing entity, Apollo Client can automatically update that entity's value in its cache when the mutation returns. To do so, the mutation must return the id of the modified entity, along with the values of the fields that were modified. Conveniently, mutations do this by default in Apollo Client.

Let's look at an example that enables us to modify the value of any existing item in our to-do list:

1const UPDATE_TODO = gql`
2  mutation UpdateTodo($id: String!, $type: String!) {
3    updateTodo(id: $id, type: $type) {
4      id
5      type
6    }
7  }
8`;
9
10function Todos() {
11  const { loading, error, data } = useQuery(GET_TODOS);
12  const [updateTodo] = useMutation(UPDATE_TODO);
13
14  if (loading) return <p>Loading...</p>;
15  if (error) return <p>Error :(</p>;
16
17  return data.todos.map(({ id, type }) => {
18    let input;
19
20    return (
21      <div key={id}>
22        <p>{type}</p>
23        <form
24          onSubmit={e => {
25            e.preventDefault();
26            updateTodo({ variables: { id, type: input.value } });
27
28            input.value = '';
29          }}
30        >
31          <input
32            ref={node => {
33              input = node;
34            }}
35          />
36          <button type="submit">Update Todo</button>
37        </form>
38      </div>
39    );
40  });
41}

1const UPDATE_TODO = gql`
2  mutation UpdateTodo($id: String!, $type: String!) {
3    updateTodo(id: $id, type: $type) {
4      id
5      type
6    }
7  }
8`;
9
10const Todos = () => (
11  <Query query={GET_TODOS}>
12    {({ loading, error, data }) => {
13      if (loading) return <p>Loading...</p>;
14      if (error) return <p>Error :(</p>;
15
16      return data.todos.map(({ id, type }) => {
17        let input;
18
19        return (
20          <Mutation mutation={UPDATE_TODO} key={id}>
21            {updateTodo => (
22              <div>
23                <p>{type}</p>
24                <form
25                  onSubmit={e => {
26                    e.preventDefault();
27                    updateTodo({ variables: { id, type: input.value } });
28
29                    input.value = '';
30                  }}
31                >
32                  <input
33                    ref={node => {
34                      input = node;
35                    }}
36                  />
37                  <button type="submit">Update Todo</button>
38                </form>
39              </div>
40            )}
41          </Mutation>
42        );
43      });
44    }}
45  </Query>
46);

If you execute the UPDATE_TODO mutation using this component, the mutation returns both the id of the modified to-do item and the item's new type. Because Apollo Client caches entities by id, it knows how to automatically update the corresponding entity in its cache. The application's UI also updates immediately to reflect changes in the cache.

Making all other cache updates

If a mutation modifies multiple entities, or if it creates or deletes entities, the Apollo Client cache is not automatically updated to reflect the result of the mutation. To resolve this, your call to useMutation can include an update function.

The purpose of an update function is to modify your cached data to match the modifications that a mutation makes to your back-end data. In the example in Executing a mutation, the update function for the ADD_TODO mutation should add the same item to our cached version of the to-do list.

The following sample illustrates defining an update function in a call to useMutation:

1const GET_TODOS = gql`
2  query GetTodos {
3    todos
4  }
5`;
6
7function AddTodo() {
8  let input;
9  const [addTodo] = useMutation(
10    ADD_TODO,
11    {
12      update(cache, { data: { addTodo } }) {
13        const { todos } = cache.readQuery({ query: GET_TODOS });
14        cache.writeQuery({
15          query: GET_TODOS,
16          data: { todos: todos.concat([addTodo]) },
17        });
18      }
19    }
20  );
21
22  return (
23    <div>
24      <form
25        onSubmit={e => {
26          e.preventDefault();
27          addTodo({ variables: { type: input.value } });
28          input.value = "";
29        }}
30      >
31        <input
32          ref={node => {
33            input = node;
34          }}
35        />
36        <button type="submit">Add Todo</button>
37      </form>
38    </div>
39  );
40}

1const GET_TODOS = gql`
2  query GetTodos {
3    todos
4  }
5`;
6
7const AddTodo = () => {
8  let input;
9
10  return (
11    <Mutation
12      mutation={ADD_TODO}
13      update={(cache, { data: { addTodo } }) => {
14        const { todos } = cache.readQuery({ query: GET_TODOS });
15        cache.writeQuery({
16          query: GET_TODOS,
17          data: { todos: todos.concat([addTodo]) },
18        });
19      }}
20    >
21      {addTodo => (
22        <div>
23          <form
24            onSubmit={e => {
25              e.preventDefault();
26              addTodo({ variables: { type: input.value } });
27              input.value = '';
28            }}
29          >
30            <input
31              ref={node => {
32                input = node;
33              }}
34            />
35            <button type="submit">Add Todo</button>
36          </form>
37        </div>
38      )}
39    </Mutation>
40  );
41};

As shown, the update function is passed a cache object that represents the Apollo Client cache. This object provides readQuery and writeQuery functions that enable you to execute GraphQL operations on the cache as though you're interacting with a GraphQL server.

Learn more about supported cache functions in Interacting with cached data.

The update function is also passed an object with a data property that contains the result of the mutation. Use this value to update the cache with cache.writeQuery.

If your mutation specifies an optimistic response, your update function is called twice: once with the optimistic result, and again with the actual result of the mutation when it returns.

In the example above, the update function first reads the existing to-do list from the cache with cache.readQuery. It then adds the new to-do item from our mutation to the list and writes it back to the cache with cache.writeQuery.

Any changes you make to cached data inside of an update function are automatically broadcast to queries that are listening for changes to that data. Consequently, your application's UI will update to reflect newly cached values.

Gotchas

Keep in mind that in order for readQuery to find the query, it must have been executed already, and the call must include the same variables. The cached object returned is immutable. To update data in the cache, create a replacement object to pass to writeQuery.

Tracking loading and error states

The useMutation hook provides mechanisms for tracking the loading and error state of a mutation.

Let's revisit the Todos component from Updating a single existing entity:

1function Todos() {
2  const { loading: queryLoading, error: queryError, data } = useQuery(
3    GET_TODOS,
4  );
5
6  const [
7    updateTodo,
8    { loading: mutationLoading, error: mutationError },
9  ] = useMutation(UPDATE_TODO);
10
11  if (queryLoading) return <p>Loading...</p>;
12  if (queryError) return <p>Error :(</p>;
13
14  return data.todos.map(({ id, type }) => {
15    let input;
16
17    return (
18      <div key={id}>
19        <p>{type}</p>
20        <form
21          onSubmit={e => {
22            e.preventDefault();
23            updateTodo({ variables: { id, type: input.value } });
24
25            input.value = '';
26          }}
27        >
28          <input
29            ref={node => {
30              input = node;
31            }}
32          />
33          <button type="submit">Update Todo</button>
34        </form>
35        {mutationLoading && <p>Loading...</p>}
36        {mutationError && <p>Error :( Please try again</p>}
37      </div>
38    );
39  });
40}

1const Todos = () => (
2  <Query query={GET_TODOS}>
3    {({ loading, error, data }) => {
4      if (loading) return <p>Loading...</p>;
5      if (error) return <p>Error :(</p>;
6
7      return data.todos.map(({ id, type }) => {
8        let input;
9
10        return (
11          <Mutation mutation={UPDATE_TODO} key={id}>
12            {(updateTodo, { loading, error }) => (
13              <div>
14                <p>{type}</p>
15                <form
16                  onSubmit={e => {
17                    e.preventDefault();
18                    updateTodo({ variables: { id, type: input.value } });
19
20                    input.value = '';
21                  }}
22                >
23                  <input
24                    ref={node => {
25                      input = node;
26                    }}
27                  />
28                  <button type="submit">Update Todo</button>
29                </form>
30                {loading && <p>Loading...</p>}
31                {error && <p>Error :( Please try again</p>}
32              </div>
33            )}
34          </Mutation>
35        );
36      });
37    }}
38  </Query>
39);

As shown above, we can destructure the loading and error properties from the result object returned by useMutation to track the mutation's state in our UI. The useMutation hook also supports onCompleted and onError options if you prefer to use callbacks.

Learn about all of the fields returned by useMutation in the API reference.

useMutation API

Supported options and result fields for the useMutation hook are listed below.

Most calls to useMutation can omit the majority of these options, but it's useful to know they exist. To learn about the useMutation hook API in more detail with usage examples, see the API reference.

Options

The useMutation hook accepts the following options:

Result

The useMutation result is a tuple with a mutate function in the first position and an object representing the mutation result in the second position.

You call the mutate function to trigger the mutation from your UI.

Mutate function:

Mutation result:

Next steps

The useQuery and useMutation hooks together represent Apollo Client's core API for performing GraphQL operations. Now that you're familiar with both, you can begin to take advantage of Apollo Client's full feature set, including:

• Optimistic UI: Learn how to improve perceived performance by returning an optimistic response before your mutation result comes back from the server.

• Local state: Use Apollo Client to manage the entirety of your application's local state by executing client-side mutations.

• Caching in Apollo: Dive deep into the Apollo Client cache and how it's normalized. Understanding the cache is helpful when writing update functions for your mutations!