Editing Shelf Status

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:

// src/features/shelf/StatusEditor.tsx
import { useState } from "react";
import { useMutation, useQueryClient } from "@tanstack/react-query";
import type { ShelfItemDto, ShelfStatus } from "../../lib/types";
import { updateProgress } from "../../api/reading";
import { useAuth } from "../auth/AuthContext";

export default function StatusEditor({ item }: { item: ShelfItemDto }) {
  const { user } = useAuth();
  const qc = useQueryClient();
  const [selected, setSelected] = useState<ShelfStatus>(item.status);

  const mutation = useMutation({
    mutationFn: (status: ShelfStatus) =>
      updateProgress({
        userId: user!.sub,
        bookId: item.bookId,
        currentPage: item.currentPage,
        status,
      }),
    onMutate: async (status) => {
      // cancel running queries to avoid clobbering our optimistic update
      await qc.cancelQueries({ queryKey: ["shelf"] });
      // define the query key we are going to manipulate
      const key = ["shelf", { status: "", sortBy: "updatedAt", order: "desc" }];
      // take a snapshot of the current shelf data so we can roll back if needed
      const previous = qc.getQueryData<ShelfItemDto[]>(key);
      // immediately update the cache with the new status for this book
      qc.setQueryData<ShelfItemDto[]>(key, (old) =>
        old?.map((it) => (it.bookId === item.bookId ? { ...it, status } : it)) || []
      );
      // update local state to reflect the button highlight
      setSelected(status);
      return { previous, key };
    },
    onError: (_e, _vars, ctx) => {
      if (ctx?.previous && ctx.key) qc.setQueryData(ctx.key, ctx.previous);
      setSelected(item.status);
    },
    onSettled: () => {
      qc.invalidateQueries({ queryKey: ["shelf"] });
    },
  });

  const Btn = ({ value, label }: { value: ShelfStatus; label: string }) => (
    <button
      type="button"
      onClick={() => mutation.mutate(value)}
      disabled={mutation.isLoading}
      className={
        `px-2 py-1 rounded-md text-xs border transition-colors ` +
        (selected === value
          ? "bg-sky-600 border-sky-500 text-white"
          : "bg-slate-700 border-slate-600 text-slate-200 hover:bg-slate-600") +
        (mutation.isLoading ? " opacity-80 cursor-wait" : "")
      }
      aria-pressed={selected === value}
    >
      {label}
    </button>
  );

  return (
    <div className="flex flex-wrap gap-2 items-center mt-2" aria-label="Update status">
      <Btn value="want-to-read" label="Want to read" />
      <Btn value="not-started" label="Not started" />
      <Btn value="in-progress" label="In progress" />
      <Btn value="completed" label="Completed" />
    </div>
  );
}

• A local selected state tracks the currently highlighted status for immediate visual feedback.

• useMutation is configured with updateProgress, sending both currentPage and the new status.

• onMutate provides optimistic UI:

  • Cancels ongoing shelf queries.
  • Stores the previous shelf data so we can roll back if needed.
  • Updates the cache immediately so the UI reflects the change right away.
  • Updates local state with setSelected(status).

• onError restores the previous state if something fails.

• onSettled invalidates the shelf query, ensuring eventual consistency with the backend.

• The qc variable is a query client instance provided by React Query. It acts as the gateway to the entire query cache: letting us cancel queries, read cached data (getQueryData), update cached data (setQueryData), and request fresh data (invalidateQueries). Without the query client, optimistic UI would not be possible, because components would only react to server responses instead of cache manipulations.

• In onMutate, we first call qc.cancelQueries to stop any in-flight requests that might overwrite our optimistic changes. We then snapshot the current cache (getQueryData) and update it with the new status (setQueryData). This makes the UI respond instantly, before the network request finishes. Finally, we update local component state so the currently selected button is highlighted.

• The Btn is a locally defined inner component inside StatusEditor. We do this because these buttons are tightly coupled to the logic and state of StatusEditor. Defining it inline avoids the overhead of a separate file, keeps all relevant code in one place, and makes it easy to reuse the same styles and behavior across multiple status values. Since the button’s only purpose is to render status-specific options and trigger mutations, a standalone component would add unnecessary indirection.

This combination of cache manipulation with the query client (qc) and a local inline Btn definition gives us a fast, responsive, and maintainable way to let users update shelf status in real time. This ensures that a click on a status button feels instant while still being reliable.