Welcome back! In the last lessons, you learned how to fetch your reading shelf and update your reading progress. Now, let’s take the next step: editing the status of a book on your shelf.

Shelf status is a simple way to track where you are with each book. For example, you might want to mark a book as “Want to read,” “In progress,” or “Completed.” This helps you organize your reading and see your progress at a glance.

In this lesson, you will learn how to let users change the status of a book directly from their shelf. This is a key feature for any modern reading app, and it builds on what you’ve already learned about React state and optimistic UI updates.

The StatusEditor component is responsible for letting users change the status of a book. It displays a set of buttons, one for each possible status. When you click a button, the status for that book is updated and the change is reflected immediately in the UI.

Here’s the main part of the StatusEditor component:

By now, you’ve learned the basics of queries (for fetching data) and mutations (for changing data). In this project, editing shelf status combines both concepts:

• Queries (useQuery) are responsible for fetching the shelf and keeping it cached.
• Mutations (useMutation) are responsible for sending updates (like changing status) to the server.
• The Query Client (qc) links them together: it cancels, updates, or refetches queries when a mutation runs.

The Role of Queries

The shelf view (MyShelfPage) uses useQuery to fetch shelf entries from the backend:

• Each shelf item is displayed with its current status.
• The shelf query is cached by React Query, keyed by ["shelf", { status, sortBy, order }].
• Whenever filters or sorting change, React Query automatically refetches new data.

This means the shelf is always driven by server state, but still benefits from caching for performance.

The Role of Mutations

When you edit a book’s status in StatusEditor, a mutation runs:

1. Send the change to the server via updateProgress.
2. Optimistically update the cache with the new status.
3. Rollback if the request fails.

Here’s how they work together step by step:

1. The shelf page (useQuery) loads the current books and their statuses.
2. The user clicks a status button.
3. useMutation runs with the new status.
   • onMutate: cancels active queries, snapshots the old cache, updates the cache optimistically.
   • onError: restores the snapshot if the request fails.
   • onSettled: invalidates the shelf query so the UI syncs with the backend.
4. The shelf query refetches, pulling in the authoritative state from the server.

Why This Matters

• Fast feedback: Users see the new status immediately.
• Error safety: If the server rejects the change, the app rolls back seamlessly.
• Consistency: The final refetch guarantees the frontend and backend match.

🔑 Key Takeaways

• Queries keep the shelf data fresh and cache results.
• Mutations apply changes and manage optimistic updates.
• The Query Client ties them together with cancel, set, and invalidate methods.
• This combination makes the shelf status editor feel smooth, responsive, and reliable.

Let’s look more closely at how the status update works when you click a button.

Explanation:

• When you click a status button, mutation.mutate(value) is called.
• The onMutate function is used for an optimistic update. It updates the UI right away, before the server responds.
• The selected status is updated in the UI, and the shelf data in the cache is also updated.
• This makes the app feel fast and responsive.

Output:
When you click a new status, the button highlights immediately, even before the server confirms the change.

Sometimes, the update might fail (for example, if there’s a network problem). The StatusEditor handles this by rolling back to the previous state:

Explanation:

• If the update fails, onError restores the previous shelf data and resets the selected status.
• After the mutation is done (whether it succeeded or failed), onSettled refreshes the shelf data from the server to make sure everything is up to date.

Output:
If there’s an error, the status button goes back to what it was before, so the user always sees the correct information.

In this lesson, you learned how to let users edit the status of a book on their shelf. You saw how the StatusEditor component works, how optimistic updates make the UI feel fast, and how errors are handled to keep the data accurate.

You are now ready to practice these skills on your own.