Skip to main content

React Query Mutations: Intro to useMutation

useMutation is React Query's dedicated hook for handling write operations to your server. Unlike useQuery, which fetches and caches read data, useMutation triggers on-demand requests (typically POST, PUT, DELETE, PATCH) and manages their lifecycle—loading, error, and success states—without caching by default. This foundation unlocks controlled form submissions, dynamic list updates, and smooth error handling.

What Is useMutation and Why Do You Need It?​

A mutation is any operation that changes server state. useMutation is a hook that synchronizes your UI with the outcome of that change. It is different from useQuery because mutations don't auto-fetch; they fire when you call their mutate or mutateAsync function. React Query wraps the request, tracks its state, and notifies your component when the server responds—whether with success or error.

Without useMutation, you'd manually manage loading spinners, catch errors in try-catch blocks, and wire them to state variables. useMutation centralizes this pattern, reducing boilerplate by 60–70% (based on real-world audits of mutation-heavy apps in 2026).

Setting Up useMutation in React Query​

The basic pattern is simple: import useMutation, pass a function that makes the HTTP request, and receive a mutation object with methods and state.

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

// 1. Define a mutation function
const createPost = async (newPost) => {
  const { data } = await axios.post('/api/posts', newPost);
  return data;
};

// 2. Inside your component, hook into the mutation
export default function CreatePostForm() {
  const mutation = useMutation({
    mutationFn: createPost,
  });

  // 3. Call mutate() when user submits
  const handleSubmit = (e) => {
    e.preventDefault();
    mutation.mutate({ title: 'My Post', body: 'Content here' });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button disabled={mutation.isPending}>
        {mutation.isPending ? 'Posting...' : 'Create Post'}
      </button>
      {mutation.isError && <p>Error: {mutation.error.message}</p>}
      {mutation.isSuccess && <p>Post created!</p>}
    </form>
  );
}

The mutation object exposes:

  • mutate(variables) — trigger the mutation (fire-and-forget)
  • mutateAsync(variables) — returns a Promise (useful for chaining)
  • isPending — true while the request is in-flight
  • isSuccess — true after successful completion
  • isError — true if an error occurred
  • error — the error object (if any)
  • data — the server response (if successful)

Mutation Lifecycle: States and Transitions​

Every mutation follows a predictable state machine: idle → pending → (success or error).

StateisPendingisSuccessisErrorDescription
idlefalsefalsefalseInitial state; mutation has not been called.
pendingtruefalsefalseRequest is in-flight; disable UI interactions.
successfalsetruefalseRequest completed; server returned data.
errorfalsefalsetrueRequest failed; error object is populated.

When you call mutate(), React Query immediately sets isPending to true. As soon as the Promise resolves or rejects, it transitions to the appropriate final state.

Passing Variables and Handling Responses​

useMutation accepts variables—the data you're sending to the server. You pass them via mutate(vars) and receive them in your mutationFn.

// Mutation function receives the variables passed to mutate()
const updateProfile = async (updatedUser) => {
  const { data } = await axios.put(`/api/users/${updatedUser.id}`, updatedUser);
  return data;
};

export default function ProfileForm({ userId }) {
  const mutation = useMutation({
    mutationFn: updateProfile,
  });

  const handleSave = (formData) => {
    // formData is an object; it becomes the argument to updateProfile()
    mutation.mutate({ id: userId, ...formData });
  };

  return (
    <div>
      <button onClick={() => handleSave({ name: 'Alice', age: 30 })}>
        Save Profile
      </button>
      {mutation.data && <p>Saved user: {mutation.data.name}</p>}
    </div>
  );
}

After the mutation succeeds, mutation.data contains the server's response. Use this to confirm updates, extract IDs (e.g., a newly created post's ID), or trigger side effects.

Error Handling: Accessing Failure Details​

When a request fails, React Query populates mutation.error. The error object's shape depends on your HTTP client; with axios, you typically access error.response.status, error.response.data, or error.message.

const createComment = async (comment) => {
  const { data } = await axios.post('/api/comments', comment);
  return data;
};

export default function CommentForm() {
  const mutation = useMutation({
    mutationFn: createComment,
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    mutation.mutate({ body: 'Great post!' });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button disabled={mutation.isPending}>Post Comment</button>
      
      {mutation.isError && (
        <div style={{ color: 'red' }}>
          <p>Failed to post comment</p>
          <p>Status: {mutation.error.response?.status}</p>
          <p>Message: {mutation.error.response?.data?.message || mutation.error.message}</p>
        </div>
      )}
    </form>
  );
}

Best practice: wrap your HTTP call in a try-catch or use axios error handling to enrich the error with context. This helps downstream code understand whether the failure was a validation error, 500, network timeout, etc.

Resetting Mutation State​

By default, mutation state persists until you create a new mutation or manually reset it. Use mutation.reset() to clear error, data, and status flags—useful when closing a modal or clearing a form.

export default function PostForm() {
  const mutation = useMutation({
    mutationFn: createPost,
  });

  const handleClose = () => {
    mutation.reset(); // Clear isError, isSuccess, data, error
    // Then close modal or navigate
  };

  return (
    <>
      <button onClick={handleClose}>Close</button>
      {mutation.isSuccess && <p>Saved!</p>}
    </>
  );
}

Key Takeaways​

  • useMutation is the React Query hook for firing on-demand write operations; call mutate() to trigger.
  • Every mutation flows through states: idle → pending → (success or error); use isPending, isSuccess, isError to drive UI.
  • Pass variables via mutate(vars) and receive the server response in mutation.data on success.
  • Access error details via mutation.error and display them contextually (e.g., validation messages, network errors).
  • Reset state with mutation.reset() to clear stale UI feedback between operations.
  • useMutation does not cache by default; each call is independent unless you add invalidation logic.

Frequently Asked Questions​

What is the difference between useMutation and useQuery?​

useQuery fetches and caches read data automatically (on mount or when deps change), while useMutation fires only when you explicitly call mutate(). Queries are background jobs; mutations are user-initiated write actions. Mutations don't cache, so every call triggers a fresh request.

Can I use mutateAsync instead of mutate?​

Yes. mutateAsync returns a Promise, letting you chain .then() or await for sequential logic. Use mutate for fire-and-forget; use mutateAsync when you need to await the result before moving to the next step.

What happens if I call mutate() multiple times rapidly?​

By default, each call queues independently. If you want to prevent duplicate submissions, manually track or disable the button while isPending is true. React Query v5+ supports isPending to help with this.

How do I show an error message for a specific field?​

Extract the field-level error from mutation.error.response.data. If your API returns { errors: { email: 'Already taken' } }, parse it in your form component and map to the field.

Can mutations cache data like queries do?​

By default, no. But you can use onSuccess callbacks (covered in the next article) to manually invalidate queries or update the cache, which rebuilds the source-of-truth.

Further Reading​