Optimistic Updates

When you optimistically update your state before performing a mutation, there is a non-zero chance that the mutation will fail. In most cases, you can just trigger a refetch for your optimistic queries to revert them to their true server state. In some circumstances though, refetching may not work correctly and the mutation error could represent some type of server issue that won't make it possible to refetch. In this event, you can instead choose to rollback your update.

To do this, useMutation's onMutate handler option allows you to return a value that will later be passed to both onError and onSettled handlers as the last argument. In most cases, it is most useful to pass a rollback function.

Updating a list of todos when adding a new todo

1 useMutation(updateTodo, {
2   // When mutate is called:
3   onMutate: newTodo => {
4     // Cancel any outgoing refetches (so they don't overwrite our optimistic update)
5     queryCache.cancelQueries('todos')
6 
7     // Snapshot the previous value
8     const previousTodos = queryCache.getQueryData('todos')
9 
10     // Optimistically update to the new value
11     queryCache.setQueryData('todos', old => [...old, newTodo])
12 
13     // Return the snapshotted value
14     return () => queryCache.setQueryData('todos', previousTodos)
15   },
16   // If the mutation fails, use the value returned from onMutate to roll back
17   onError: (err, newTodo, rollback) => rollback(),
18   // Always refetch after error or success:
19   onSettled: () => {
20     queryCache.invalidateQueries('todos')
21   },
22 })

Updating a single todo

1 useMutation(updateTodo, {
2   // When mutate is called:
3   onMutate: newTodo => {
4     // Cancel any outgoing refetches (so they don't overwrite our optimistic update)
5     queryCache.cancelQueries(['todos', newTodo.id])
6 
7     // Snapshot the previous value
8     const previousTodo = queryCache.getQueryData(['todos', newTodo.id])
9 
10     // Optimistically update to the new value
11     queryCache.setQueryData(['todos', newTodo.id], newTodo)
12 
13     // Return a rollback function
14     return () => queryCache.setQueryData(['todos', newTodo.id], previousTodo)
15   },
16   // If the mutation fails, use the rollback function we returned above
17   onError: (err, newTodo, rollback) => rollback(),
18   // Always refetch after error or success:
19   onSettled: newTodo => {
20     queryCache.invalidateQueries(['todos', newTodo.id])
21   },
22 })

You can also use the onSettled function in place of the separate onError and onSuccess handlers if you wish:

1 useMutation(updateTodo, {
2   // ...
3   onSettled: (newTodo, error, variables, rollback) => {
4     if (error) {
5       rollback()
6     }
7   },
8 })