Submitting Data with useMutation

1. Queries vs. Mutations: Reading vs. Writing

Before we dive into the code, let's clarify the conceptual difference between a query and a mutation.

• A query is a request to read data. It's declarative and designed to run automatically to keep your UI synchronized with the server.
• A mutation is a request to change data (create, update, delete). It's an action with side effects.

This distinction has a fundamental impact on how the hooks are designed.

As the article highlights, you wouldn't want a "create post" mutation to fire automatically every time you focus the browser window. Instead, useMutation gives you a function that you call explicitly, for example, when a user clicks a "Submit" button.

2. The useMutation Hook in Action

Let's look at the basic structure of useMutation. It's very similar to useQuery but with a few key differences.

Let's break down the core components from that example:

1. mutationFn: This is the only required option. It's an asynchronous function that performs the side effect on the server (e.g., making a POST or PATCH request) and must return a promise.
2. mutate function: The useMutation hook returns an object, one of whose properties is a function called mutate. You call this function to trigger the mutation. The first argument you pass to mutate will be passed as the first argument to your mutationFn.
3. Status Flags: Just like useQuery, useMutation provides flags to help you build a responsive UI:
   • isPending: true while the mutationFn is executing. This is the equivalent of isLoading in useQuery. You'd typically show a spinner or disable the submit button during this state.
   • isSuccess: true if the mutationFn promise resolves successfully. You might show a success message or redirect the user.
   • isError: true if the mutationFn promise is rejected.
   • error: If isError is true, this property contains the error object.

Here is a simplified example of a component for adding a post:

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

// The function that will be called by the mutation
const createPost = async (newPost) => {
  const { data } = await axios.post('/api/posts', newPost);
  return data;
};

function AddPostForm() {
  const mutation = useMutation({ mutationFn: createPost });

  const handleSubmit = (event) => {
    event.preventDefault();
    // Call mutate with the data for the new post
    mutation.mutate({ title: 'My New Post', body: '...' });
  };

  return (
    <div>
      <button onClick={handleSubmit} disabled={mutation.isPending}>
        {mutation.isPending ? 'Submitting...' : 'Create Post'}
      </button>

      {mutation.isError && (
        <div>An error occurred: {mutation.error.message}</div>
      )}

      {mutation.isSuccess && <div>Post created successfully!</div>}
    </div>
  );
}

This code directly addresses today's learning outcome by demonstrating how to use the hook and its status flags to manage the entire lifecycle of a data submission.

3. Handling Side Effects with Callbacks

What if you want to run some code only after a mutation succeeds or fails? useMutation provides helpful callback options for this.

The most common callbacks are:

• onSuccess: Fires when the mutation is successful. It receives the data returned from your mutationFn. This is the perfect place to show a success notification or, as we'll see in the next lesson, to update the client's state.
• onError: Fires when the mutation fails. It receives the error object. You can use this for logging errors to a service.
• onSettled: Fires after the mutation is either successful or has errored. This is useful for code that needs to run regardless of the outcome, like hiding a loading indicator.

Here's our previous example, now with an onSuccess callback to show an alert:

function AddPostForm() {
  const mutation = useMutation({ 
    mutationFn: createPost,
    onSuccess: (data) => {
      // 'data' is the response from our 'createPost' function
      alert(`Post created with ID: ${data.id}`);
    }
  });

  // ... rest of the component
}

4. mutate vs. mutateAsync

You might see another function returned from useMutation called mutateAsync. It's important to understand the difference.

To summarize:

• mutate: "Fire-and-forget". It doesn't return a promise. You handle side effects using the onSuccess and onError callbacks. This is the recommended approach for most use cases.
• mutateAsync: Returns a promise that resolves with the success data or throws an error. This can be useful if you need to chain promises, but it requires you to write your own try...catch block to handle errors.

For most component-level logic, sticking with mutate and its callbacks leads to cleaner and safer code.

Conclusion

Congratulations! You've now learned how to perform the "write" operations in the client-server relationship using TanStack Query. You're no longer limited to just fetching data; you can now build fully interactive experiences.

Key Takeaways:

• useMutation is an imperative hook used to create, update, or delete server data.
• You trigger it by calling the mutate function, passing the variables your mutationFn needs.
• It provides status flags (isPending, isSuccess, isError) that allow you to easily update your UI based on the state of the request.
• Side effects, like showing notifications, are best handled in the onSuccess, onError, and onSettled callbacks.

Next Lesson Preview:

We've created a post, but our list of posts doesn't know about it yet! We would have to manually refresh the page to see the new item. In the next lesson, we will solve this crucial problem. You'll learn how to use the QueryClient to invalidate queries after a mutation, which tells TanStack Query to automatically refetch the relevant data and keep your UI perfectly in sync with the server.