Search params and URL state

One page, a different list for each address

In Dynamic routes, the address picked which tea a page showed: /teas/green. Now the shop wants a search. A visitor types green, and the list shows only the green teas. Where does the word green go? The usual answer on the web is the address itself: /teas?q=green.

The part after the ? is the query string. It holds pairs of a name and a value, written name=value and joined by &: ?q=green&page=2. Each pair is a search param. Next.js gives a page all of them in a prop called searchParams. Here is the shop's list of teas, which reads one search param, q. Like every example in this lesson, it's a real Next.js 16.4.3 project, built with next build and run with next start, and what it sent back was recorded. Open the Browser tab and pick each address above the page.

1import { Suspense } from "react";2import { findTeas } from "./data";3 4export default function TeasPage({ searchParams }: PageProps<"/teas">) {5  return (6    <main>7      <h1>Our teas</h1>8      <Suspense fallback={<p>Loading teas…</p>}>9        <TeaList searchParams={searchParams} />10      </Suspense>11    </main>12  );13}14 15async function TeaList({ searchParams }: { searchParams: Promise<{ q?: string | string[] }> }) {16  const { q } = await searchParams;17  const teas = findTeas(typeof q === "string" ? q : "");18 19  if (teas.length === 0) return <p>No teas match.</p>;20  return (21    <ul>22      {teas.map((tea) => (23        <li key={tea.slug}>{tea.name}</li>24      ))}25    </ul>26  );27}

One file, app/teas/page.tsx, answers all four addresses. Line by line:

• Line 4: Next.js calls TeasPage with a searchParams prop. Like params, it's a promise.
• Lines 8 to 10 put TeaList inside Suspense, with Loading teas… as the fallback, so the build has something to show while the list waits for the query string.
• Line 16 waits for searchParams and takes q out of it. Line 17 keeps the teas whose name contains q, with findTeas from app/teas/data.ts. A name can be given twice, so q can be an array; line 17 only searches when it's one string, and shows every tea otherwise.
• Line 19 shows No teas match. when nothing is left.

The Browser tab shows six teas for /teas, Green tea and Jasmine green tea for /teas?q=green, Mint tea for /teas?q=mint, and No teas match. for /teas?q=coffee. The Terminal lists one route, ◐ /teas: the legend says (Partial Prerender) prerendered as static HTML with dynamic server-streamed content. The heading and the fallback were made once, during the build, as the page's shell. The list was made for each request, from its query string. The Network tab shows both in each response's HTML: Loading teas… first, then the list.

The searchParams prop

What does the object look like? This page prints the searchParams it gets, as text, with JSON.stringify on line 15. The recorder asked it for seven addresses. Pick each one above the page.

1import { Suspense } from "react";2 3export default function TeasPage({ searchParams }: PageProps<"/teas">) {4  return (5    <main>6      <h1>Our teas</h1>7      <Suspense fallback={<p>Loading…</p>}>8        <ShowSearchParams searchParams={searchParams} />9      </Suspense>10    </main>11  );12}13 14async function ShowSearchParams({ searchParams }: { searchParams: Promise<object> }) {15  return <p>searchParams: {JSON.stringify(await searchParams)}</p>;16}

Each row is one address from that recording, and the object the page printed for it:

So, when you read a search param:

• It may be missing. /teas gave {}, so q is undefined. Give it a default.
• It's a string. page is "2", not 2. Turn it into a number with Number(page) before you count with it.
• It may be an array. ?q=mint&q=green gave ["mint","green"]. Check with typeof q === "string", as line 17 of the teas page does.
• It's a plain object, not the browser's URLSearchParams: read q with destructuring, not .get("q").

Like params, searchParams is a promise, because the query string isn't known during the build: the server receives it with each request. With params, a shop can list its teas ahead of time. A query string can be anything a visitor types, so it can't be listed: the part that reads it waits inside Suspense. Pick each version, and read the Terminal.

1import { findTeas } from "./data";2 3export default async function TeasPage({ searchParams }: PageProps<"/teas">) {4  const { q } = await searchParams;5  const teas = findTeas(typeof q === "string" ? q : "");6 7  return (8    <main>9      <h1>Our teas</h1>10      <ul>11        {teas.map((tea) => (12          <li key={tea.slug}>{tea.name}</li>13        ))}14      </ul>15    </main>16  );17}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...Error: Route "/teas": Next.js encountered uncached or runtime data during prerendering. `fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience. Ways to fix this:  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)  - [block] Set `export const instant = false` to allow a blocking route Learn more: https://nextjs.org/docs/messages/blocking-prerender-dynamic    at body (<anonymous>)    at html (<anonymous>)To get a more detailed stack trace and pinpoint the issue, try one of the following:  - Start the app in development mode by running `next dev`, then open "/teas" in your browser to investigate the error.  - Rerun the production build with `next build --debug-prerender` to generate better stack traces.Error occurred prerendering page "/teas". Read more: https://nextjs.org/docs/messages/prerender-errorExport encountered an error on /teas/page: /teas, exiting the build.⨯ Next.js build worker exited with code: 1 and signal: null

Awaited at the top, the build stops: Route "/teas": Next.js encountered uncached or runtime data during prerendering. Awaited inside Suspense, it builds as ◐ /teas. The more of the page that sits outside the Suspense, the more of it is ready in the shell: here, the nav and the heading. The Rendering and caching stage covers request-time data in full.

useSearchParams and the Suspense it needs

The shop wants a search box that shows what was searched for. A box reacts to typing, so it's a Client Component. Pages start as Server Components, which run only on the server; a file that starts with "use client" marks where the client part begins, and its components, and what it imports, also run in the browser. A Client Component reads the query string with the useSearchParams hook:

"use client";

import { useSearchParams } from "next/navigation";

export default function SearchBox() {
  const searchParams = useSearchParams();

  return <input name="q" placeholder="Search teas" defaultValue={searchParams.get("q") ?? ""} />;
}

This file is part of the recorded projects below; it runs there, not in this page. Line 3 imports useSearchParams from next/navigation. Line 6 calls it. It returns a read-only URLSearchParams, the browser's own object for a query string, so line 8 reads q with .get("q"): "mint" on /teas?q=mint, or null without one, which ?? "" turns into an empty box.

During the build, there is no query string to give the hook. So, like await searchParams, the component needs a Suspense around it, with something to show meanwhile. Each button is one version of the teas page with this box. Before you click, guess what each build does, and what the HTML for /teas?q=mint holds.

1import SearchBox from "./search-box";2 3export default function TeasPage() {4  return (5    <main>6      <h1>Our teas</h1>7      <SearchBox />8    </main>9  );10}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...Error: Route "/teas": Next.js encountered URL data `useSearchParams()` in a Client Component outside of `<Suspense>`. This blocks prerendering because the value is only available at runtime. Ways to fix this:  - [stream] Wrap the component in `<Suspense fallback={...}>` so the hook value streams in after prerendering  - [block] Set `export const instant = false` to allow a blocking route Learn more: https://nextjs.org/docs/messages/blocking-prerender-client-hook    at <unknown> (app/teas/search-box.tsx:6:24)    at main (<anonymous>)    at body (<anonymous>)    at html (<anonymous>)  4 |  5 | export default function SearchBox() {> 6 |   const searchParams = useSearchParams();    |                        ^  7 |  8 |   return <input name="q" placeholder="Search teas" defaultValue={searchParams.get("q") ?? ""} />;  9 | } {  digest: 'CLIENT_HOOK_DYNAMIC'}To get a more detailed stack trace and pinpoint the issue, try one of the following:  - Start the app in development mode by running `next dev`, then open "/teas" in your browser to investigate the error.  - Rerun the production build with `next build --debug-prerender` to generate better stack traces.Error occurred prerendering page "/teas". Read more: https://nextjs.org/docs/messages/prerender-errorExport encountered an error on /teas/page: /teas, exiting the build.⨯ Next.js build worker exited with code: 1 and signal: null

Without Suspense, the build stops at line 6 of search-box.tsx: Next.js encountered URL data useSearchParams() in a Client Component outside of <Suspense>. With it, what happens depends on the rest of the page:

• Nothing else reads the request. The page is the same for everyone, so the build makes it once: ○ /teas, (Static) prerendered as static content. Its HTML holds the fallback, Loading the search box…, for every query string. Open the Steps tab: in real Chrome, once the page's JavaScript ran, the box showed mint. The browser drew it.
• The list reads searchParams. The page is now made for each request, ◐ /teas, and the server renders the box along with it. The Network tab shows value="mint" in the HTML.

Each row is one version: what the build does, and what the HTML for /teas?q=mint holds.

Which to use? In a page, read the searchParams prop: the server can use the values to load data, and pass them to any component as props. In a Client Component deep in the page, or one a layout uses, call useSearchParams, and put a Suspense as close around it as you can, so the rest stays in the shell.

Updating the URL without a reload

Reading the address is half of it. The box should also change the address as the visitor types, so the list follows. Here is the shop with that box, two teas a page, and links to the other pages. The file shown first is the box. Read it, then open the Steps tab.

1import Link from "next/link";2import { findTeas } from "./data";3 4const perPage = 2;5 6export default async function TeaList({ searchParams }: { searchParams: PageProps<"/teas">["searchParams"] }) {7  const { q, page } = await searchParams;8  const query = typeof q === "string" ? q : "";9  const current = Number(page) || 1;10  const found = findTeas(query);11  const pages = Math.max(1, Math.ceil(found.length / perPage));12  const shown = found.slice((current - 1) * perPage, current * perPage);13  const link = (to: number) => ({ pathname: "/teas", query: query ? { q: query, page: to } : { page: to } });14 15  return (16    <>17      <ul>18        {shown.map((tea) => (19          <li key={tea.slug}>{tea.name}</li>20        ))}21      </ul>22      <p>23        Page {current} of {pages}24      </p>25      {current > 1 && <Link href={link(current - 1)}>Previous</Link>}{" "}26      {current < pages && <Link href={link(current + 1)}>Next</Link>}27    </>28  );29}

Lines 6 to 8 call three hooks from next/navigation: useSearchParams for the query string, usePathname for the path, /teas, and useRouter for the router, which can move to another address from code. On every change, line 23 calls search with the box's text:

• Line 11 copies the current query string into a new URLSearchParams, which, unlike the read-only one, can change.
• Lines 12 and 13 set q to the text, or delete it when the box is empty. Line 14 deletes page: a new search starts on page 1.
• Line 15 turns the pairs back into text, like q=green. Line 16 calls router.replace with the new address: /teas?q=green, or just /teas.

router.replace is a client-side navigation: Next.js's router changes the address and asks the server only for the new page's data, an RSC payload, instead of loading a whole HTML page (the first look at how Next.js works introduced both). The Steps tab shows it, recorded in real Chrome. Step 1 opens /teas, a page load. Step 2 clicks Next: the address becomes /teas?page=2, with one request, a fetch. Step 3 types green in the box: the address becomes /teas?q=green, page is gone, and the list shows Green tea and Jasmine green tea. Again one fetch, and no page load. The box kept its text and its focus, because the page was never loaded again.

The Next link in step 2 comes from app/teas/tea-list.tsx. Its href is an object: a pathname and a query. Link turns it into an address:

<Link href={{ pathname: "/teas", query: { q: "tea", page: 2 } }}>Next</Link>

This is a fragment of tea-list.tsx, with the values filled in. The recorded /teas?q=tea page has exactly this link: <a href="/teas?q=tea&page=2">. A link is an ordinary <a>, so it works before the JavaScript loads, and Next.js's router takes over the click once it has.

Why replace and not push? Both navigate the same way. Next.js's docs describe the difference: router.push adds an entry to the browser's history, so Back returns to the address before, while router.replace swaps the current entry. A search box changes the address on every letter; with replace, Back doesn't step through g, gr, gre. A Link pushes, which suits page links: Back goes to the page before. Linking and navigating covers the router in full.

Search and pages for the tea shop

Now the list itself. It reads two search params, q and page, shows two teas a page, and links to the pages before and after. Open the Browser tab, and click Next and Previous: each link switches to its recorded page.

1import Link from "next/link";2import { findTeas } from "./data";3 4const perPage = 2;5 6export default async function TeaList({ searchParams }: { searchParams: PageProps<"/teas">["searchParams"] }) {7  const { q, page } = await searchParams;8  const query = typeof q === "string" ? q : "";9  const current = Number(page) || 1;10  const found = findTeas(query);11  const pages = Math.max(1, Math.ceil(found.length / perPage));12  const shown = found.slice((current - 1) * perPage, current * perPage);13  const link = (to: number) => ({ pathname: "/teas", query: query ? { q: query, page: to } : { page: to } });14 15  return (16    <>17      <ul>18        {shown.map((tea) => (19          <li key={tea.slug}>{tea.name}</li>20        ))}21      </ul>22      <p>23        Page {current} of {pages}24      </p>25      {current > 1 && <Link href={link(current - 1)}>Previous</Link>}{" "}26      {current < pages && <Link href={link(current + 1)}>Next</Link>}27    </>28  );29}

• Line 7 waits for searchParams and takes q and page. Line 8 keeps q only when it's one string.
• Line 9 turns page into a number. Number("2") is 2. A missing page, or text like abc, gives NaN or 0, and || 1 turns those into page 1.
• Line 11 counts the pages, and line 12 takes this page's two teas with slice.
• Line 13 builds each link's href, keeping q so the search survives a change of page. Lines 25 and 26 show Previous and Next only when there's a page to go to.

The recording shows the result for every address the box and the links lead to: /teas?q=tea has five teas, so Page 1 of 3, and its Next link is /teas?q=tea&page=2. /teas?page=1 shows the same teas as /teas. Each of these addresses can be shared: whoever opens it gets the same page of the same search, made on the server.

URL state or component state?

Not everything belongs in the address. State in a component, with useState, lives in the browser, for as long as the component is on screen. State in the URL lives in the address. Each row asks one question of both:

There is a third way, for URL state only the browser needs. Next.js's docs say you can also call the browser's own window.history.pushState and window.history.replaceState. They change the address without a reload, and useSearchParams and usePathname follow the change. The docs' example uses it for a sort order that a Client Component applies to a list it already has.

A good rule: if someone would want it in a link they share, or the server needs it to make the page, put it in the URL. If it's private, short-lived or changes many times a second, keep it in the component. Sort these:

Common mix-ups

• "searchParams is a URLSearchParams." No. The prop is a promise of a plain object. Only useSearchParams returns a URLSearchParams, with .get().
• "?page=2 gives the number 2." No. The recorded page got "2", a string. Use Number(page).
• "Each name has one value." No. ?q=mint&q=green gave an array.
• "useSearchParams works anywhere." It works in Client Components, inside a Suspense. Without one, the recorded build stopped.
• "Changing the query string reloads the page." No. In real Chrome, router.replace and a Link changed it with a fetch, and the box kept its text.
• "Search params make the whole page dynamic." Only the part that waits for them, inside Suspense. The heading and the nav were in the shell, made during the build.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

/teas?sort=price&sort=name

/teas?q=mint&page=2

<Link href={{ pathname: "/teas", query: { q: "tea", page: 2 } }}>Next</Link>

import { Suspense } from "react";
import { findTeas } from "./data";

export default function TeasPage({ searchParams }: PageProps<"/teas">) {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Loading teas…</p>}>
        <TeaList searchParams={searchParams} />
      </Suspense>
    </main>
  );
}

async function TeaList({ searchParams }: { searchParams: Promise<{ q?: string | string[] }> }) {
  const { q } = await searchParams;
  const teas = findTeas(typeof q === "string" ? q : "");

  if (teas.length === 0) return <p>No teas match.</p>;
  return (
    <ul>
      {teas.map((tea) => (
        <li key={tea.slug}>{tea.name}</li>
      ))}
    </ul>
  );
}

import SearchBox from "./search-box";

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <SearchBox />
    </main>
  );
}

import { Suspense } from "react";
import SearchBox from "./search-box";

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Loading the search box…</p>}>
        <SearchBox />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import SearchBox from "./search-box";

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Loading the search box…</p>}>
        <SearchBox />
      </Suspense>
    </main>
  );
}

Check your understanding

For each question, ask who has the query string at that moment: the build, the server on a request, or the browser.

Key takeaways

• The query string, after the ?, is state kept in the address. Pages get it in the searchParams prop.
• searchParams is a promise of a plain object. Values are strings, or arrays when a name repeats, and may be missing.
• A query string isn't known during the build, and the server receives it with each request, so the part that reads it waits inside Suspense; the rest stays in the shell.
• Client Components read it with useSearchParams, inside Suspense, and change it with router.replace or a Link with a query, without a reload.
• Put state in the URL when it should be shared, survive a reload, or be read by the server. Keep the rest in components.

Coming next: Route groups and private folders. Folders in brackets group routes without changing the address, and folders that start with _ stay out of routing.