Fetching User Shelf

Introduction: What Is the User's Shelf?

Welcome to the first lesson of this course on building a modern React frontend with a NestJS API . In this lesson, you will learn how to fetch and display a user's personalized reading shelf . The "shelf" is a feature that lets users keep track of books they are reading, want to read, or have finished. By the end of this lesson, you will understand how to retrieve this shelf data from the backend and show it in the frontend, setting the stage for more advanced features later.

Project Setup And Key Files

To get oriented, let’s look at the main files used in this feature. These are the building blocks that combine backend API calls, type safety, and UI components into a single working page. Each file has a distinct responsibility, which helps keep our project modular and easy to extend. Here is the structure relevant to this unit: plaintext src/ api/ reading.ts # Functions to call the backend API for shelf data lib/ types.ts # Type definitions for shelf items and parameters features/ shelf/ MyShelfPage.tsx # Main page to display the user's shelf ShelfFilters.tsx # UI controls for filtering and sorting the shelf components/ Skeleton.tsx # Loading placeholder component App.tsx # Main app layout and navigation src/lib/types.ts provides strong type definitions for shelf data, ensuring consistency with backend responses. src/api/reading.ts centralizes API calls, so our UI never has to deal with raw HTTP logic. src/features/shelf/MyShelfPage.tsx is the main React page where the shelf is rendered. src/features/shelf/ShelfFilters.tsx contains the dropdowns and buttons that let users change filters. src/components/Skeleton.tsx provides a placeholder while data loads. src/App.tsx manages navigation and adds prefetching so shelf data feels instant. Together, these files provide everything we need to build a polished and responsive shelf page.

Backend Route: /reading/shelf

Before we start coding, it is important to understand how the backend serves shelf data. The backend provides a protected endpoint that responds only when a valid authentication token is supplied, ensuring users can only access their own data. This endpoint supports query parameters for filtering and sorting, allowing us to provide a dynamic and user-friendly shelf view. Understanding this route is critical because our frontend logic will closely mirror these query options. GET /reading/shelf (Protected: requires authentication) Purpose: Returns the current user’s shelf entries, enriched with book details such as title, author, and progress. Query params (all optional): status: one of 'not-started' | 'in-progress' | 'completed' | 'want-to-read' sortBy: one of 'title' | 'author' | 'updatedAt' | 'progress' order: 'asc' | 'desc' Response shape: JSON{ "bookId": 2, "title": "Dune", "author": "Frank Herbert", "progress": 0.24, "currentPage": 100, "status": "in-progress", "updatedAt": "2025-09-21T12:30:00.000Z" } Note: You can always test the backend routes on your own. During the practices, open a new terminal and send a curl request to the desired route to check the output. For protected routes, you’ll need to log in with the correct credentials and include the access token in your request headers. For example, you can log in as admin and capture the access token like this: ShellADMIN_TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"admin"}' \ | sed -E 's/.*"access_token":"?([^",}]+).*/\1/') echo "ADMIN_TOKEN: ${ADMIN_TOKEN}" Once logged in, you can use that token to access protected routes. For example, here’s how Alice could view her shelf entries filtered by status and sorted by progress in descending order: Shellcurl -s -H "Authorization: Bearer ${ALICE_TOKEN}" \ "http://localhost:3000/reading/shelf?status=in-progress&sortBy=progress&order=desc" We go through this process in detail in our Building the Reading Tracker API with NestJS path, where we defined the backend, created all the routes from scratch, and explained the purpose and usage of each one.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Filter Controls in the UI

To let users filter and sort their shelf view, we introduce a dedicated filter component. This component includes dropdowns for filtering by reading status and sorting by different fields, as well as a button to toggle the sort order. By encapsulating this logic in its own component, we keep the main page clean and make it easier to maintain or enhance filters later.

TSX

// src/features/shelf/ShelfFilters.tsx
export default function ShelfFilters({
  status, sortBy, order, onChange,
}: {
  status: string; sortBy: string; order: 'asc' | 'desc';
  onChange: (next: {status?: string; sortBy?: string; order?: 'asc'|'desc'}) => void;
}) {
  return (
    <div className="mb-4 flex gap-2 items-end">
      <select
        value={status}
        onChange={(e) => onChange({ status: e.target.value || undefined })}
        className="bg-slate-800 p-2 rounded-md"
      >
        <option value="">All statuses</option>
        <option value="want-to-read">Want to read</option>
        <option value="in-progress">In progress</option>
        <option value="completed">Completed</option>
        <option value="not-started">Not started</option>
      </select>

      <select
        value={sortBy}
        onChange={(e) => onChange({ sortBy: e.target.value })}
        className="bg-slate-800 p-2 rounded-md"
      >
        <option value="updatedAt">Recent updates</option>
        <option value="title">Title</option>
        <option value="author">Author</option>
        <option value="progress">Progress</option>
      </select>

      <button
        className="bg-slate-700 px-3 py-2 rounded-md"
        onClick={() => onChange({ order: order === 'asc' ? 'desc' : 'asc' })}
      >
        {order === 'asc' ? 'Asc' : 'Desc'}
      </button>
    </div>
  );
}

// src/features/shelf/ShelfFilters.tsx
export default function ShelfFilters({
  status, sortBy, order, onChange,
}: {
  status: string; sortBy: string; order: 'asc' | 'desc';
  onChange: (next: {status?: string; sortBy?: string; order?: 'asc'|'desc'}) => void;
}) {
  return (
    <div className="mb-4 flex gap-2 items-end">
      <select
        value={status}
        onChange={(e) => onChange({ status: e.target.value || undefined })}
        className="bg-slate-800 p-2 rounded-md"
      >
        <option value="">All statuses</option>
        <option value="want-to-read">Want to read</option>
        <option value="in-progress">In progress</option>
        <option value="completed">Completed</option>
        <option value="not-started">Not started</option>
      </select>

      <select
        value={sortBy}
        onChange={(e) => onChange({ sortBy: e.target.value })}
        className="bg-slate-800 p-2 rounded-md"
      >
        <option value="updatedAt">Recent updates</option>
        <option value="title">Title</option>
        <option value="author">Author</option>
        <option value="progress">Progress</option>
      </select>

      <button
        className="bg-slate-700 px-3 py-2 rounded-md"
        onClick={() => onChange({ order: order === 'asc' ? 'desc' : 'asc' })}
      >
        {order === 'asc' ? 'Asc' : 'Desc'}
      </button>
    </div>
  );
}

The status dropdown lets users filter by reading phase (in-progress, completed, etc.).
The sorting dropdown offers different sorting criteria like title, author, or progress.
The button toggles between ascending and descending order.
Each change triggers onChange, which updates the parent’s state and re-queries the backend.

This UI layer is simple but powerful, allowing end users to interact with the backend via query parameters seamlessly.

Fetching And Displaying Shelf Data In React

Now, let’s see how the frontend fetches and displays this shelf data. The main logic is in MyShelfPage.tsx, which uses React Query to manage data fetching and state.

Here is the key part of the code:

TypeScript

import { useQuery } from "@tanstack/react-query";
import { useSearchParams } from "react-router-dom";
import { getShelf } from "../../api/reading";
import Skeleton from "../../components/Skeleton";
import ShelfFilters from "./ShelfFilters";

export default function MyShelfPage() {
  const [sp, setSp] = useSearchParams();
  const status = sp.get("status") || "";
  const sortBy = sp.get("sortBy") || "updatedAt";
  const order = (sp.get("order") as "asc" | "desc") || "desc";

  const { data, isLoading, isError } = useQuery({
    queryKey: ["shelf", { status, sortBy, order }],
    queryFn: () => getShelf({ status: status as any, sortBy: sortBy as any, order }),
    keepPreviousData: true,
  });

  // ...rendering code
}

import { useQuery } from "@tanstack/react-query";
import { useSearchParams } from "react-router-dom";
import { getShelf } from "../../api/reading";
import Skeleton from "../../components/Skeleton";
import ShelfFilters from "./ShelfFilters";

export default function MyShelfPage() {
  const [sp, setSp] = useSearchParams();
  const status = sp.get("status") || "";
  const sortBy = sp.get("sortBy") || "updatedAt";
  const order = (sp.get("order") as "asc" | "desc") || "desc";

  const { data, isLoading, isError } = useQuery({
    queryKey: ["shelf", { status, sortBy, order }],
    queryFn: () => getShelf({ status: status as any, sortBy: sortBy as any, order }),
    keepPreviousData: true,
  });

  // ...rendering code
}

Explanation:

We call useSearchParams to synchronize filters with the URL, making the shelf view shareable and bookmarkable.
The useQuery hook extracts data, isLoading, and isError from the API call.
The queryKey uniquely identifies the query in React Query’s cache, ensuring data is refetched when filters change.
queryFn calls our getShelf helper, passing in the current status, sortBy, and order.
keepPreviousData: true avoids UI flickers by showing old results until new data arrives.

This design abstracts away manual fetch management and gives us a clean, declarative way to work with server state.

Rendering the shelf:

TypeScript

return (
  <section aria-live="polite">
    <h1 className="text-3xl font-bold mb-2">My Shelf</h1>
    <ShelfFilters status={status} sortBy={sortBy} order={order} onChange={onChange} />
    {isLoading && <Skeleton lines={4} />}
    {isError && <p className="text-red-400">Failed to load your shelf.</p>}
    {!isLoading && !isError && (
      <>
        {data?.length ? (
          <ul className="space-y-3">
            {data.map((item) => (
              <li key={item.bookId} className="bg-slate-800 p-4 rounded-lg">
                <div className="font-semibold text-sky-400">{item.title}</div>
                <div className="text-slate-400">by {item.author}</div>
                <div className="mt-1 text-sm">
                  Page {item.currentPage} • {Math.round(item.progress * 100)}% • {item.status}
                </div>
              </li>
            ))}
          </ul>
        ) : (
          <p className="text-slate-400">Your shelf is empty. Visit the Catalog to add books.</p>
        )}
      </>
    )}
  </section>
);

return (
  <section aria-live="polite">
    <h1 className="text-3xl font-bold mb-2">My Shelf</h1>
    <ShelfFilters status={status} sortBy={sortBy} order={order} onChange={onChange} />
    {isLoading && <Skeleton lines={4} />}
    {isError && <p className="text-red-400">Failed to load your shelf.</p>}
    {!isLoading && !isError && (
      <>
        {data?.length ? (
          <ul className="space-y-3">
            {data.map((item) => (
              <li key={item.bookId} className="bg-slate-800 p-4 rounded-lg">
                <div className="font-semibold text-sky-400">{item.title}</div>
                <div className="text-slate-400">by {item.author}</div>
                <div className="mt-1 text-sm">
                  Page {item.currentPage} • {Math.round(item.progress * 100)}% • {item.status}
                </div>
              </li>
            ))}
          </ul>
        ) : (
          <p className="text-slate-400">Your shelf is empty. Visit the Catalog to add books.</p>
        )}
      </>
    )}
  </section>
);

What happens here:

While loading, a skeleton placeholder is shown.
If there’s an error, an error message is displayed.
If data is loaded and not empty, each book is shown in a list.
If the shelf is empty, a message is shown to the user.

Operation	Type	React Query Hook	Example in this app
Read data	Query	`useQuery`	Fetching shelf
Change data	Mutation	`useMutation`	Updating progress

Introduction: What Is the User's Shelf?

Project Setup And Key Files

Backend Route: /reading/shelf

Join the 1M+ learners on CodeSignal

Shelf Types in TypeScript

How The Shelf API Works

Filter Controls in the UI

Providing Feedback with Skeleton Loaders

Fetching And Displaying Shelf Data In React

Connecting Filters To The Shelf View

Prefetching Shelf Data for Faster Navigation

Deep Dive: Understanding Queries with useQuery

What is a Query?

Why useQuery?

Anatomy of useQuery

Query Lifecycle

Example in This Project

Summary And Practice Preview