Search Params & Query State

Lesson 6 — typed, URL-driven UI state for filters, tabs, modals

Filters, sort order, pagination, "which modal is open" — these belong in the URL, not in useState. TanStack Router makes search params first-class and fully typed: declare a schema per route, read with a hook, write with navigation. Share the URL, refresh the page, hit back — the state survives all of it.

Why URL State, Not useState

State in useState dies on refresh, can't be shared, can't be deep-linked. URL state survives everything:

• Refresh — filters persist
• Share — paste the URL, recipient sees identical view
• Back button — natural undo
• Analytics — which filters are popular?

If the user would ever want to share or return to a UI state, it goes in the URL.

validateSearch — the schema

Every route can declare a validateSearch function. It receives raw parsed params and returns a typed object. The returned shape becomes the type of search everywhere downstream — components, child routes, loaders.

// routes/_app/(tabs)/feed/index.tsx
type SortOption = 'newest' | 'oldest' | 'top'

type FeedSearch = {
  page: number
  filter: string
  sort: SortOption
}

export const Route = createFileRoute('/_app/(tabs)/feed')({
  validateSearch: (raw: Record<string, unknown>): FeedSearch => ({
    page: Number(raw?.page ?? 1),
    filter: (raw.filter as string) || '',
    sort: (raw.sort as SortOption) || 'newest',
  }),
  component: FeedList,
})

With Zod (recommended)

Zod collapses validation + typing into one declaration. Pass the schema directly:

import { z } from 'zod'

const feedSearchSchema = z.object({
  page: z.number().catch(1),
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'oldest', 'top']).catch('newest'),
})

export const Route = createFileRoute('/_app/(tabs)/feed')({
  // Pass the schema object directly — TanStack calls .parse for you
  validateSearch: feedSearchSchema,
})

Reading Search Params

Three ways, same data:

// 1. Inside this route's component — typed hook on Route
function FeedList() {
  const { page, filter, sort } = Route.useSearch()
  //    ^? { page: number, filter: string, sort: SortOption }
  return <>...</>
}

// 2. Outside this route (e.g. a sidebar component) — useSearch with from
import { useSearch } from '@tanstack/react-router'
const { page } = useSearch({ from: '/_app/(tabs)/feed' })

// 3. Loosen typing when route is unknown
const search = useSearch({ strict: false })
//    ^? { page?: number, filter?: string, ... }

For deep components in a code-split tree, use getRouteApi('/...') instead of importing the Route object — avoids circular deps.

Writing Search Params

Writing is a navigation. Use navigate({ search }) or <Link search>. The search prop is a function of previous — never throw away params you didn't touch:

import { useNavigate } from '@tanstack/react-router'

function FeedControls() {
  const navigate = useNavigate({ from: Route.fullPath })

  return (
    <>
      {/* Pagination: only touches `page`, preserves filter + sort */}
      <button onClick={() => navigate({
        search: (prev) => ({ ...prev, page: prev.page + 1 })
      })}>
        Next page
      </button>

      {/* Via Link: same function form */}
      <Link
        to="/_app/(tabs)/feed"
        search={(prev) => ({ ...prev, sort: 'top' })}
      >
        Sort by top
      </Link>
    </>
  )
}

Next.js → TanStack Quick Map

The shift: Next.js treats search params as a raw string you parse manually. TanStack treats them as a typed object you declare a schema for, then read and write with hooks — invalid values never reach your component.

Practice Exercise

The Feed screen needs filter UI: a text filter input, a sort dropdown (newest | top), and pagination. All state in the URL. Build:

1. The validateSearch schema (Zod, all params with .catch() fallbacks)
2. A component reading filter, sort, page via Route.useSearch()
3. A filter input that writes filter and resets page to 1

Sketch mentally, then reveal.

import { z } from 'zod'
import { createFileRoute, useNavigate } from '@tanstack/react-router'

const feedSearch = z.object({
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'top']).catch('newest'),
  page: z.number().catch(1),
})

export const Route = createFileRoute('/_app/(tabs)/feed')({
  validateSearch: feedSearch,
  component: FeedList,
})

function FeedList() {
  const { filter, sort, page } = Route.useSearch()
  const navigate = useNavigate({ from: Route.fullPath })

  return (
    <div>
      <input
        value={filter}
        onChange={(e) => navigate({
          // Reset page to 1 when filter changes — fresh result set
          search: (prev) => ({ ...prev, filter: e.target.value, page: 1 })
        })}
      />
      <select
        value={sort}
        onChange={(e) => navigate({
          search: (prev) => ({ ...prev, sort: e.target.value })
        })}
      >
        <option value="newest">Newest</option>
        <option value="top">Top</option>
      </select>
      <span>Page {page}</span>
    </div>
  )
}

Quick Quiz

Primary source: TanStack Router — Search Params (Validating, Reading, and Writing sections). Read after the quiz to see the full validateSearch + Zod integration.