Skip to content
Reusable List

Reusable List Page Architecture

One list-page system. Four distinct product surfaces.

An interactive showcase of URL-driven search, filtering, sorting, pagination, view switching, selection, bulk actions, and explicit system states—built from one reusable Next.js architecture.

Explore examplesRead the architecture

Next.js · React · TypeScript · Tailwind CSS · shadcn/ui

TL;DR

The project separates repeatable list mechanics from domain-specific presentation. URL parsing, controls, result layouts, pagination, selection primitives, and system states live in a shared core, while each feature owns its records, filters, query service, toolbar composition, and renderers.

Four examples prove the boundary with different data shapes and interaction needs. The accompanying reference pages explain how the pieces compose, what each primitive does, and how data moves between the URL, Server Components, Client Components, and mock Route Handlers.

Four examples, one foundation

Each route reuses the same list-page architecture while keeping its domain decisions local.

  • Components

    A component catalog with multi-value framework filtering, category and status filters, sorting, pagination, and list/grid views.

    • Multi-select filters
    • List and grid
    • Active filters
    Open Components

  • Issues

    An issue tracker that extends the shared foundation with semantic table rendering, row selection, select-all, and demo-only bulk status actions.

    • Row selection
    • Bulk actions
    • Failure recovery
    Open Issues

  • Deployments

    A deployment history with environment, branch, status, and date-range filtering plus domain-specific status and relative-time presentation.

    • Date range
    • Status filters
    • Domain formatting
    Open Deployments

  • Packages

    A dependency inventory with package-specific version ordering, dependency-type filtering, update status, and reusable list/grid rendering.

    • Version sorting
    • Update status
    • List and grid
    Open Packages

Shared core vs. page-owned code

Shared core

src/features/list-page/
  • Query parsing and serialization
  • Search, filters, sorting, and views
  • Results layout and pagination
  • Active filters
  • Selection primitives
  • Loading, empty, and error states

Page-owned feature

src/features/issues-example/
  • Types and mock records
  • Query configuration and service
  • Toolbar composition
  • Rows, cards, and domain presentation
  • Bulk-action behavior where applicable

Features compose the shared core without modifying it.

Designed around durable boundaries

  1. URL as state — Search, filters, sorting, view, and pagination remain shareable and restorable.
  2. Server-first results — Pages parse the URL, call domain query services directly, and render results on the server.
  3. Focused client boundaries — Client Components handle interactive controls, temporary selection, bulk-action state, and recovery.
  4. One domain query function — Each page and its mock Route Handler reuse the same configuration and query service.
  5. Explicit system states — Loading, empty, filtered-empty, and error behavior are part of the architecture rather than afterthoughts.

Read the system from three angles

  • Templates

    See how the primitives compose into progressively richer list-page patterns.

    View Templates

  • Building Blocks

    Inspect the shared components, hooks, functions, types, boundaries, and real consumers.

    View Building Blocks

  • Architecture

    Follow the request-to-render flow, server/client responsibilities, query pipeline, and selection exception.

    View Architecture

Built to demonstrate engineering decisions, not just screens.

The mock data and Route Handlers keep the project self-contained. The reusable boundaries, accessible interactions, responsive behavior, and explicit trade-offs are the actual product being demonstrated.

Start with Components