Week 9: Mutations, Optimistic Updates & Cancellation

1. useMutation

Where useQuery is for reads that run automatically, useMutation is for writes you trigger explicitly — creating a todo, updating a profile, deleting a comment. It gives you a mutate function and status flags, with no automatic execution on render.

import { useMutation } from '@tanstack/react-query';

function AddTodoForm() {
  const { mutate, isPending, isError } = useMutation({
    mutationFn: (text: string) =>
      fetch('/api/todos', {
        method: 'POST',
        body: JSON.stringify({ text }),
        headers: { 'Content-Type': 'application/json' },
      }).then(res => res.json()),
  });

  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const text = new FormData(e.currentTarget).get('text') as string;
    mutate(text);
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="text" />
      <button disabled={isPending}>{isPending ? 'Adding...' : 'Add'}</button>
      {isError && <p>Something went wrong.</p>}
    </form>
  );
}

mutationFn is the async function that performs the write. mutate(text) calls it with whatever argument you pass, and isPending/isError track its status — the same status-flag shape as useQuery, applied to a write instead of a read.

2. Invalidating Queries

A successful mutation on the server doesn't automatically update anything already cached from Week 8's queries — the todos list query still holds whatever it fetched before the new todo existed. Invalidation tells TanStack Query "this cached data might be wrong now, refetch it":

import { useMutation, useQueryClient } from '@tanstack/react-query';

function AddTodoForm() {
  const queryClient = useQueryClient(); // access to the shared cache

  const { mutate, isPending } = useMutation({
    mutationFn: (text: string) => createTodo(text),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] }); // refetch anything keyed ['todos', ...]
    },
  });

  // ...
}

invalidateQueries marks every query whose key matches (or starts with) ['todos'] as stale and triggers a background refetch for any that are currently in use — so the todos list re-renders with the new item shortly after the mutation succeeds, with zero manual cache-editing on your part.

3. Optimistic Updates

Invalidation still means waiting for a refetch after the mutation resolves — for a fast action like toggling a todo's checkbox, that round-trip delay is noticeable and feels sluggish. An optimistic update updates the cache immediately, assuming success, and rolls back only if the mutation actually fails.

function useToggleTodo() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (id: number) => toggleTodoOnServer(id),

    onMutate: async (id: number) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] }); // avoid a race with an in-flight refetch

      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);

      queryClient.setQueryData<Todo[]>(['todos'], old =>
        old?.map(todo => (todo.id === id ? { ...todo, done: !todo.done } : todo))
      );

      return { previousTodos }; // saved for rollback in onError
    },

    onError: (_err, _id, context) => {
      if (context?.previousTodos) {
        queryClient.setQueryData(['todos'], context.previousTodos); // roll back
      }
    },

    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] }); // reconcile with the server either way
    },
  });
}

Four lifecycle callbacks work together here: onMutate runs before the network request, snapshotting the current cache and applying the optimistic change; onError restores that snapshot if the server rejects the mutation; onSettled runs after either outcome and invalidates to reconcile the cache with whatever the server actually ended up with. The checkbox flips instantly on click — the network request happens invisibly behind that instant feedback.

4. Loading/Error UI Patterns

A few small conventions make loading and error states feel considered rather than bolted on. First: distinguish the very first load of a query from a background refetch of already-cached data — isPending only reflects "no data yet at all," while isFetching is also true during any background refetch.

function TodoList() {
  const { data: todos, isPending, isFetching, isError } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  });

  if (isPending) return <Skeleton />;            // truly nothing to show yet
  if (isError) return <p>Couldn't load todos.</p>;

  return (
    <div>
      {isFetching && <span className="subtle-spinner" />} {/* refreshing existing data */}
      <ul>{todos.map(todo => <li key={todo.id}>{todo.text}</li>)}</ul>
    </div>
  );
}

This distinction matters for feel: replacing the whole list with a full-page spinner on every background refetch (like the window-refocus refetch from Week 8) is jarring; a small, unobtrusive indicator while the existing data stays visible reads as "quietly keeping this fresh" instead of "reloading."

5. Request Cancellation

If a query's inputs change before the previous request finishes — typing quickly in a search box, navigating away from a page mid-fetch — the old request is wasted work. TanStack Query passes an AbortSignal into queryFn, wired to cancel automatically when a query becomes obsolete:

useQuery({
  queryKey: ['search', query],
  queryFn: async ({ signal }) => {
    const response = await fetch(`/api/search?q=${query}`, { signal });
    return response.json();
  },
});

Passing signal straight to fetch is enough — if the query changes again before this request resolves (making this exact query key obsolete), TanStack Query aborts the in-flight request via that signal automatically. The browser stops the network request outright, rather than just ignoring its result the way Week 2's hand-written ignore flag did — genuinely canceling wasted work instead of merely discarding it after the fact.

6. useOptimistic: React's Own Optimistic-Update Primitive

Section 3's optimistic pattern lives entirely inside TanStack Query's cache — you manually snapshot the previous value in onMutate and manually restore it in onError. That's the right tool when the optimistic value needs to appear everywhere that query is read (a todo's checked state shown in both a list and a detail view). When the optimistic value is local to one piece of UI — or there's no TanStack cache involved at all, as with the Server Actions in Week 20 — React 19's built-in useOptimistic does the same revert-on-settle bookkeeping without the manual snapshot/rollback code.

import { useOptimistic, useState } from 'react';

function LikeButton({ postId, initialLikes }: { postId: number; initialLikes: number }) {
  const [likes, setLikes] = useState(initialLikes);
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    likes,
    (current, amount: number) => current + amount,
  );

  async function handleLike() {
    addOptimisticLike(1); // shows immediately
    const updated = await likePost(postId); // real request, runs in the background
    setLikes(updated.likes); // reconciles with the server's real count
  }

  return <button onClick={handleLike}>❤️ {optimisticLikes}</button>;
}

useOptimistic(state, updateFn) takes the real, confirmed state and an updater, and returns a temporary "optimistic" value plus a function to set it. Whenever the surrounding async work finishes — whether likePost above resolves or throws — React automatically reverts optimisticLikes back to whatever likes actually is, with no onError to write by hand. The trade-off: this optimistic value is local to this component's state; it doesn't update a shared cache the way queryClient.setQueryData does, so a different component reading the same "real" like count elsewhere won't see it.

7. Hands-on Exercise

8. Knowledge Check

Four quick questions. Expand each to check your answer.