Optimistic Updates

When you optimistically update your state before performing a mutation, there is a chance that the mutation will fail. In most of these failure 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 const queryClient = useQueryClient()
2 
3 useMutation(updateTodo, {
4   // When mutate is called:
5   onMutate: async newTodo => {
6     // Cancel any outgoing refetches (so they don't overwrite our optimistic update)
7     await queryClient.cancelQueries('todos')
8 
9     // Snapshot the previous value
10     const previousTodos = queryClient.getQueryData('todos')
11 
12     // Optimistically update to the new value
13     queryClient.setQueryData('todos', old => [...old, newTodo])
14 
15     // Return a context object with the snapshotted value
16     return { previousTodos }
17   },
18   // If the mutation fails, use the context returned from onMutate to roll back
19   onError: (err, newTodo, context) => {
20     queryClient.setQueryData('todos', context.previousTodos)
21   },
22   // Always refetch after error or success:
23   onSettled: () => {
24     queryClient.invalidateQueries('todos')
25   },
26 })

Updating a single todo

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

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, context) => {
4     if (error) {
5       // do something
6     }
7   },
8 })