Keeping Filters in the URL

An admin team reviews orders. You build the filter row — status buttons plus a pagination control — the obvious way:

'use client';
import { useState } from 'react';

export function OrderFilters() {
  const [status, setStatus] = useState('all');
  const [page, setPage] = useState(1);
  // fetching and filtering happen from those two values
}

It works until the product manager sends a link to a teammate: "look at these three failed orders." The teammate opens it and sees every order on page one, unfiltered. Reloading loses the view. Back does not undo a filter change. The browser cannot bookmark the view you just described in chat. The state was real; it lived in the one store the browser gives you nothing with — one component's memory.

The URL is a different kind of store. Search params are shareable, bookmarkable, survive reload and Back/Forward, and — the reason this matters in a Next.js course — the server reads the very same URL string the client sees. One value serves as the client's view-state container and the server's query input. There is nothing to serialize, nothing to hydrate, and no chance of the two sides disagreeing.

Client side, useSearchParams exposes the current params; writing them means navigating to the same path with a new query string:

// app/orders/status-filter.tsx
'use client';
import { usePathname, useRouter, useSearchParams } from 'next/navigation';

export function StatusFilter() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();
  const current = searchParams.get('status') ?? 'all';

  function select(status: string) {
    const params = new URLSearchParams(searchParams.toString());
    if (status === 'all') params.delete('status');
    else params.set('status', status);
    router.replace(`${pathname}?${params.toString()}`);
  }

  return (
    <div role='group' aria-label='Filter by status'>
      {['all', 'paid', 'failed'].map((s) => (
        <button key={s} onClick={() => select(s)} aria-pressed={current === s}>
          {s}
        </button>
      ))}
    </div>
  );
}

Two details in that function carry most of the weight. new URLSearchParams(searchParams.toString()) clones before mutating — writing straight into the hook's params drops every other param you did not touch (the page number, the search term), which surfaces later as "filters reset whenever I change the sort." And params.delete('status') when the value is all keeps the canonical URL free of ?status=all; defaults belong outside the URL.

Server side, the page reads the URL through the searchParams prop and turns it into a query:

// app/orders/page.tsx
import { db } from '@/lib/db';
import { OrderFilters } from './status-filter';
import { OrdersTable } from './orders-table';

export default async function OrdersPage({
  searchParams,
}: {
  searchParams: Promise<{ status?: string; page?: string }>;
}) {
  const { status, page } = await searchParams;
  const orders = await db.order.findMany({
    where: status ? { status } : {},
    skip: ((Number(page) ?? 1) - 1) * 25,
    take: 25,
  });

  return (
    <main>
      <OrderFilters />
      <OrdersTable rows={orders} />
    </main>
  );
}

In Next.js 15, searchParams is a Promise and you await it — in 14 it was a plain object, and that version detail comes up in interviews because it followed React's async request APIs. The page becomes an async function, or hands the awaited object to a child.

Both sides now read one source of truth. Clicking a filter navigates, Next.js fetches the route's RSC payload with the new query, the server component re-runs with the new searchParams, and the table updates. Send the URL to a teammate: their browser requests the same payload with the same params and gets the same three failed orders. This is exactly the failure the last chapter of Local State with useState and useReducer predicted — state that users expect to share has moved out of component memory. What has not been decided yet is what each navigation does to the history stack, which is the next question.

Filter a list with router.push on every click and the history fills with near-identical entries; the user presses Back five times to undo five filter tweaks and cannot tell which entry is which. Each navigation API writes a different history, and picking the wrong one is what users mean when they say the back button is broken.

The rule of thumb: if the URL is a refinement of the view already on screen, replace; if it is a different view, push. A refined view that pushes makes Back walk through five near-identical states — noise the user has to wade through to reach the page they came from. Navigational jumps should additionally be <Link> elements rather than programmatic calls, so they inherit prefetching of the route's RSC payload on hover and viewport entry.

Pagination also wants the scroll behavior disabled. Navigation scrolls to top by default, which throws the user away from the row they were reading the moment they change pages:

const params = new URLSearchParams(searchParams.toString());
params.set('page', String(next));
router.replace(`${pathname}?${params.toString()}`, { scroll: false });

What actually happens after the call is the mechanism interviewers probe. router.replace starts a client-side navigation: Next.js fetches the RSC payload for the route with the new query string, the page server component re-runs on the server with the new searchParams, and React reconciles the returned payload into the existing tree. Client components in that tree stay mounted — their own useState survives the navigation — while the server-rendered slots are swapped for new output. Any client component that reads useSearchParams re-renders because the hook subscribes to navigation, so your filter buttons update their highlighted state without an extra synchronization layer.

Until the fresh payload arrives, the previous view stays on screen. A loading.tsx file (or a <Suspense> boundary around the server-rendered section) swaps in a skeleton the instant navigation starts; without one, a slow query makes the page look frozen and users click the same filter twice, wondering.

There are two readers of the URL and it pays to keep them straight:

They always agree because both derive from the same request URL. Neither one writes. Writing happens only through client-side navigation — the URL changes first and the render follows. That inversion (a state change is a navigation) is why filters built this way inherit Back, Forward, and sharing with no extra code.

One structural note: only the page component receives the searchParams prop. Layouts do not re-render when params change, so a sidebar at the layout level that must react to filters reads useSearchParams in a client component of its own. Route groups, dynamic segments, and parallel slots all keep the same contract — params arrive at the page, and the page decides what to pass down.

The build error: useSearchParams without a Suspense boundary

A statically rendered page whose client filter calls useSearchParams fails the build with:

useSearchParams() should be wrapped in a suspense boundary at page "/orders"

Static generation needs a shell it can render without a request, and a component subscribed to search params is inherently request-dependent. The fix is to let part of the page stay static by wrapping the consumer:

import { Suspense } from 'react';

<Suspense fallback={<FilterSkeleton />}>
  <StatusFilter />
</Suspense>

A loading.tsx at the route level satisfies the same requirement. Do not silence the error by forcing the whole route dynamic — that prerenders nothing and pushes every visit onto the server.

Encoding and multi-value filters

Never concatenate query strings by hand: & separates params and most reserved characters must be encoded, so a raw filter value like R&D silently truncates the param and everything after it. Always build through URLSearchParams, which encodes for you. For filters with several active values, repeat the key instead of inventing a delimiter:

params.append('tag', 'eu');
params.append('tag', 'bulk');   // ?tag=eu&tag=bulk

On the server the param may arrive as string | string[], so normalize before use: const tags = Array.isArray(p.tag) ? p.tag : p.tag ? [p.tag] : [].

Treat every param as untrusted input

status came from a URL a user can edit. Even if your ORM parameterizes queries, whitelist before you query — an enum, a zod parse, anything that turns arbitrary strings into a known set:

const ALLOWED = new Set(['paid', 'failed']);
const status = ALLOWED.has(raw) ? raw : undefined;

A value that fails the check falls back to the default (no filter), never to an error page. Keep the check in one exported helper — parseStatus(raw) in a shared module — so the page, the filter UI, and the action's tests all interpret status identically instead of repeating the ALLOWED set in three files.

Defaults and URL length

delete defaults instead of writing them: ?status=all&page=1 pins today's defaults into every shared link forever, so when the default page size changes, old links behave differently from new ones. Keep the URL to the params that actually define the view.

That discipline also defends against the hard limit: browsers cap URLs at roughly 2000 characters. A view like "filter by these 87 ids" does not fit and will not fit. The pattern that does: persist the selection server-side and put only its identity in the URL — ?view=abc123. A URL names a view; it is not a transport for arbitrary payloads.

The stale-copy trap

The last failure is quiet. This compiles and works on first render, then misbehaves:

const [status, setStatus] = useState(searchParams.get('status')); // stale copy

useSearchParams re-renders the component when the user presses Back or Forward, but the value copied into useState on the first render never updates. Read the param during render instead — const status = searchParams.get('status') ?? 'all', as in the first chapter — or force a fresh mount with a key derived from the params. State that describes which view you are looking at belongs in the URL for exactly these reasons; state that describes how the page is being used right now — a modal's open flag, a sidebar's collapsed edge — does not identify a view and belongs in a store, which is where Global Client State with Zustand picks up.