Next.js URL Query State

Next.js URL Query State Represent filters, sorting and page state in shareable URL search parameters

Phase 15 - Filtering, Search, Sorting & Pagination Volume 04 - Professional Backend

Architecture milestone

User changes collection state

v

URL params

v

Server Component

v

Task API

v

Rendered page

Phase 15 turns an unbounded collection endpoint into a validated, queryable, stable, paginated API contract.

Collection state belongs naturally in the URL A professional Tasks screen should survive refresh and be shareable. If the user filters to HIGH priority, searches payroll, and goes to page 3, the URL should be capable of representing that state.

/tasks?priority=HIGH&search=payroll&sort=dueAt&order=asc&page=3

Figure 1 - Frontend query-state flow

User changes filter

v

Update URL search params

v

Next.js receives searchParams

v

API client builds /tasks query

v

NestJS validates query

v

Prisma executes list query

v

Page renders data + meta

The URL becomes the durable representation of collection state.

Why this matters before TanStack Query TanStack Query will later manage server-state caching, refetching, and mutations. It should not replace the URL as the authoritative representation of navigable filters and pagination when shareable URLs are useful.

import { fetchTasks } from "@/lib/api/tasks";

type SearchParams = Record< string, string | string[] | undefined >;

type TasksPageProps = {
searchParams: Promise<SearchParams>;
};

function first(value: string | string[] | undefined) {
return Array.isArray(value) ? value[0] : value;
}

export default async function TasksPage({ searchParams }: TasksPageProps) {
const params = await searchParams;

const result = await fetchTasks({ status: first(params.status), priority: first(params.priority), search: first(params.search), sort: first(params.sort) as "createdAt" | "updatedAt" | "dueAt" | "title" | undefined, order: first(params.order) as "asc" | "desc" | undefined, page: Number(first(params.page) ?? "1"), pageSize: Number(first(params.pageSize) ?? "20"), });

return (
<main>
<h1>Tasks</h1>
<p>
Page {result.meta.page} of {Math.max(result.meta.totalPages, 1)}
{" · "}{result.meta.totalItems} matching tasks
</p>

<ul>
{result.data.map((task: any) => (
<li key={task.id}>{task.title}</li>

))}
</ul>
</main>
);
}

Reset page when the filter changes A common frontend bug: the user is on page 8, changes status to a filter with only one page, then sees an empty result. When a filter/search/pageSize changes, the UI should normally reset page back to 1. Sorting may also reset page depending on product behavior.

Different state has different owners

URL state: filters/page/sort. Server state: Tasks data. Form state: filter form inputs before commit if needed. Local UI state: open/closed panels. Later TanStack Query will not erase these distinctions.