How to Use refetchQueries in Apollo Client for Data Refresh

In Apollo Client, use refetchQueries inside a mutation to automatically rerun specified queries after the mutation completes. This keeps your UI data fresh by fetching updated data from the server. You can pass an array of query names or objects to refetchQueries when calling useMutation or client.mutate.

Syntax

The refetchQueries option is used with Apollo Client mutations to specify which queries should be rerun after the mutation finishes. It accepts an array of query names or query objects.

Example parts:

• mutationFunction({ variables, refetchQueries }): Call mutation with variables and refetchQueries option.
• refetchQueries: ["QueryName"]: List of query names to rerun.
• refetchQueries: [{ query: QUERY_DOCUMENT, variables: {...} }]: List of query objects with variables.

javascript

mutationFunction({ variables, refetchQueries: ["QueryName"] })

// or

mutationFunction({ variables, refetchQueries: [{ query: QUERY_DOCUMENT, variables: { id: 1 } }] })

Example

This example shows how to use refetchQueries with useMutation to refresh a list query after adding a new item.

javascript

import { gql, useMutation, useQuery } from '@apollo/client';

const GET_ITEMS = gql`
  query GetItems {
    items {
      id
      name
    }
  }
`;

const ADD_ITEM = gql`
  mutation AddItem($name: String!) {
    addItem(name: $name) {
      id
      name
    }
  }
`;

function ItemList() {
  const { loading, error, data } = useQuery(GET_ITEMS);
  const [addItem] = useMutation(ADD_ITEM, {
    refetchQueries: ["GetItems"],
    awaitRefetchQueries: true
  });

  if (loading) return 'Loading...';
  if (error) return `Error! ${error.message}`;

  const handleAdd = () => {
    addItem({ variables: { name: "New Item" } });
  };

  return (
    <>
      <ul>
        {data.items.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
      <button onClick={handleAdd}>Add Item</button>
    </>
  );
}

Output

When the 'Add Item' button is clicked, the ADD_ITEM mutation runs, then the GET_ITEMS query is refetched, updating the list with the new item.

Common Pitfalls

Common mistakes when using refetchQueries include:

• Not specifying awaitRefetchQueries: true, which can cause UI to update before refetch completes.
• Using incorrect query names or forgetting to import the query document.
• Passing incomplete variables for queries that require them.
• Overusing refetchQueries causing unnecessary network requests.

Always ensure query names match exactly and include variables if needed.

javascript

/* Wrong way: missing awaitRefetchQueries, so UI may update too early */
addItem({ variables: { name: "Test" }, refetchQueries: ["GetItems"] });

/* Right way: await refetchQueries to finish before UI updates */
addItem({ variables: { name: "Test" }, refetchQueries: ["GetItems"], awaitRefetchQueries: true });

Quick Reference

Use this quick guide when working with refetchQueries:

Option	Description	Example
refetchQueries	Array of query names or objects to rerun after mutation	["GetItems"] or [{ query: GET_ITEMS, variables: { id: 1 } }]
awaitRefetchQueries	Boolean to wait for refetch to complete before resolving mutation	true or false
useMutation option	Pass refetchQueries and awaitRefetchQueries inside useMutation	useMutation(MUTATION, { refetchQueries: [...], awaitRefetchQueries: true })
client.mutate option	Pass refetchQueries when calling client.mutate directly	client.mutate({ mutation: MUTATION, refetchQueries: [...] })

Key Takeaways

Use refetchQueries to rerun queries after a mutation to keep UI data fresh.

Pass query names or query objects with variables to refetchQueries.

Set awaitRefetchQueries to true to wait for refetch completion before UI updates.

Ensure query names and variables are correct to avoid errors.

Avoid overusing refetchQueries to reduce unnecessary network calls.