useMutation

TanStack

Reading data is one thing. What about creating, updating, and deleting?

The Manual Way

Manual POST with try-catch, loading flags, and no cache sync. Each mutation is a pile of boilerplate.

MESSYManual loading, error, success state

The Fix: useMutation

One hook that tracks the full mutation lifecycle — idle, pending, success, error — with callbacks at every step.

CLEANidle

One hook. Status tracking, callbacks, error handling — all built in.

mutation-post.tsx

const mutation = useMutation({
  mutationFn: (title: string) =>
    fetch("/api/posts", {
      method: "POST",
      body: JSON.stringify({ title }),
    }).then(res => res.json()),
  onSuccess: (data) => {
    console.log("Created!", data);
    // queryClient.invalidateQueries({ queryKey: ["posts"] });
  },
  onError: (error) => {
    console.error("Failed:", error);
  },
});

// Usage: mutation.mutate("My new post");
// Built-in: isPending, isError, isSuccess, data, error

Before vs After

Manual POST

Manual try-catch with loading flags
No automatic retry on failure
Cache stays stale after mutation

useMutation

Built-in isPending, isError, isSuccess
onSuccess/onError callbacks + retry
Invalidate queries to refresh stale data

useMutation handles the full lifecycle: idle → pending → success/error, with callbacks at every step.

Playground

useMutation pairs with useQuery for full data management — CRUD operations, cache updates, and optimistic UI.

🗑️CRUD PostsCache Updates

Create and delete update the cache directly — no refetch needed!

crud-mutations.tsx

const queryClient = useQueryClient();

const createMutation = useMutation({
  mutationFn: (title: string) =>
    fetch("/api/posts", { method: "POST", body: JSON.stringify({ title }) })
      .then(r => r.json()),
  onSuccess: (newPost) => {
    // Update cache directly — no refetch needed!
    queryClient.setQueryData(["my-posts"], (old: Post[]) =>
      [...old, newPost]
    );
  },
});

const deleteMutation = useMutation({
  mutationFn: (id: number) =>
    fetch(`/api/posts/${id}`, { method: "DELETE" }),
  onSuccess: (_, deletedId) => {
    queryClient.setQueryData(["my-posts"], (old: Post[]) =>
      old.filter(p => p.id !== deletedId)
    );
  },
});

⚡Optimistic UpdatesInstant UI

Add a todo — it appears instantly. If the server fails (20% chance), it rolls back.

optimistic-updates.tsx

const addTodo = useMutation({
  mutationFn: (text: string) => createTodoOnServer(text),

  // Optimistic update: change UI BEFORE server responds
  onMutate: async (text) => {
    await queryClient.cancelQueries({ queryKey: ["todos"] });
    const previous = queryClient.getQueryData(["todos"]);

    // Add the todo immediately (optimistic)
    queryClient.setQueryData(["todos"], (old) => [
      ...old,
      { id: Date.now(), text, done: false },
    ]);

    return { previous }; // save for rollback
  },

  // If error: roll back to previous state
  onError: (err, text, context) => {
    queryClient.setQueryData(["todos"], context.previous);
  },

  // Always refetch after error or success
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ["todos"] });
  },
});

These are the patterns that trip up developers most often. Switch between Wrong and Fixed to compare the code side by side.

Not invalidating queries after mutation

Mutation succeeds but the UI still shows stale cached data

Don't do this

todo-form.tsx

const mutation = useMutation({
  mutationFn: (newTodo) => axios.post("/todos", newTodo),
  // Nothing happens after success — cache is stale!
});

function handleSubmit(data) {
  mutation.mutate(data);
  // List still shows old data until manual refresh
}

Mutations change server state, but the query cache doesn't know about it unless you tell it. Without invalidation, users see old data until a background refetch happens. Always invalidate related queries in onSuccess or onSettled after a mutation.

Incomplete optimistic updates

Updating the cache optimistically but forgetting rollback on error

Don't do this

todo-form.tsx

const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    // Missing: cancelQueries, snapshot, context return
    queryClient.setQueryData(["todos"], (old) => {
      old.push(newTodo); // mutates in place!
      return old;        // same reference — React won't re-render
    });
  },
  // Missing: onError rollback
  // Missing: onSettled invalidation
});

A proper optimistic update has 4 steps: cancel outgoing refetches, snapshot previous data, update immutably, and return the snapshot as context. On error, roll back to the snapshot. On settled, always invalidate to ensure server/client sync. Skipping any step creates race conditions or broken UI.

Not returning the promise from mutationFn

Forgetting to return the API call so onSuccess fires too early

Don't do this

api.tsx

const mutation = useMutation({
  mutationFn: (id) => {
    axios.delete(`/todos/${id}`); // missing return!
  },
  onSuccess: () => {
    // Fires IMMEDIATELY — server hasn't deleted yet
    queryClient.invalidateQueries({ queryKey: ["todos"] });
  },
});

If mutationFn doesn't return the promise, TanStack Query treats it as synchronously resolved. onSuccess fires immediately, invalidation triggers, and the refetch returns old data because the server hasn't processed the request yet. Always return (or use arrow shorthand) the API call.

The Fix: useMutation

One hook that tracks the full mutation lifecycle — idle, pending, success, error — with callbacks at every step.

CLEANidle

One hook. Status tracking, callbacks, error handling — all built in.

mutation-post.tsx

const mutation = useMutation({
  mutationFn: (title: string) =>
    fetch("/api/posts", {
      method: "POST",
      body: JSON.stringify({ title }),
    }).then(res => res.json()),
  onSuccess: (data) => {
    console.log("Created!", data);
    // queryClient.invalidateQueries({ queryKey: ["posts"] });
  },
  onError: (error) => {
    console.error("Failed:", error);
  },
});

// Usage: mutation.mutate("My new post");
// Built-in: isPending, isError, isSuccess, data, error

Before vs After

Manual POST

Manual try-catch with loading flags
No automatic retry on failure
Cache stays stale after mutation

useMutation

Built-in isPending, isError, isSuccess
onSuccess/onError callbacks + retry
Invalidate queries to refresh stale data

useMutation handles the full lifecycle: idle → pending → success/error, with callbacks at every step.

const mutation = useMutation({ mutationFn: (newTodo) => axios.post("/todos", newTodo), // Nothing happens after success — cache is stale! }); function handleSubmit(data) { mutation.mutate(data); // List still shows old data until manual refresh }

const mutation = useMutation({ mutationFn: updateTodo, onMutate: async (newTodo) => { // Missing: cancelQueries, snapshot, context return queryClient.setQueryData(["todos"], (old) => { old.push(newTodo); // mutates in place! return old; // same reference — React won't re-render }); }, // Missing: onError rollback // Missing: onSettled invalidation });

useMutation

The Manual Way

The Fix: useMutation

Before vs After

Playground

Common Mistakes

useMutation

The Manual Way

The Fix: useMutation

Before vs After

Playground

Common Mistakes