Search Params

Q: Por que searchParams é uma Promise em Componentes de Servidor Next.js 15+?

No Next.js 15+, searchParams é uma Promise que deve ser aguardada antes de acessar as propriedades Desestruturar sem await retorna um objeto Promise, não os valores Isso se alinha com o modelo de Componentes de Servidor assíncronos

Q: Ler searchParams no servidor impede a geração estática?

Sim, acessar searchParams em um Componente de Servidor opta a rota para renderização dinâmica A página não pode ser pré-renderizada porque os parâmetros de pesquisa só são conhecidos no momento da requisição Se você deseja uma página estática, leia os parâmetros apenas em Componentes Cliente com useSearchParams

Q: Qual a diferença entre router.push e router.replace para search params?

router.push cria uma nova entrada no histórico do navegador (o usuário pode pressionar voltar) router.replace substitui a entrada atual do histórico (melhor para filtros e ordenação) Use replace quando mudanças frequentes de parâmetros poluiriam a pilha de histórico

Q: Como lidar com parâmetros de pesquisa de múltiplos valores (ex: ?color=red&color=blue)?

searchParams.get("color") retorna apenas o primeiro valor

Q: Como tipar searchParams para uma página de Componente de Servidor em TypeScript?

Os valores podem ser string, string[] ou undefined

Q: Como usar uma key do Suspense para reativar estados de carregamento quando os parâmetros mudam?

Mudar a key desmonta e remonta o limite do Suspense, mostrando o fallback novamente

Q: Quando usar searchParams versus segmentos de rota dinâmicos como [slug]?

Use segmentos dinâmicos ([slug]) quando o parâmetro define a identidade do recurso (ex: /products/shoes) Use searchParams quando o parâmetro é um filtro ou modificador (ex: ?sort=price&page=2) Os parâmetros de pesquisa são opcionais; segmentos dinâmicos são partes obrigatórias da URL

Leia e manipule parâmetros de consulta de URL com useSearchParams (cliente) e a prop searchParams (servidor).

Receita

Cartão de receita de referência rápida -- pronto para copiar e colar.

// Componente de Servidor -- acesse searchParams como uma prop (Promise no Next.js 15+)
type Props = { searchParams: Promise<{ q?: string; page?: string }> };
 
export default async function Page({ searchParams }: Props) {
  const { q, page } = await searchParams;
  const results = await search(q, Number(page) || 1);
  return <ResultsList results={results} />;
}

// Componente Cliente -- hook useSearchParams
"use client";
import { useSearchParams, useRouter, usePathname } from "next/navigation";
 
export function SearchInput() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const pathname = usePathname();
 
  function handleSearch(term: string) {
    const params = new URLSearchParams(searchParams.toString());
    if (term) params.set("q", term);
    else params.delete("q");
    router.push(`${pathname}?${params.toString()}`);
  }
 
  return (
    <input
      defaultValue={searchParams.get("q") ?? ""}
      onChange={(e) => handleSearch(e.target.value)}
      placeholder="Search..."
    />
  );
}

Quando usar isso: Você precisa de estado controlado pela URL -- filtros de pesquisa, paginação, ordenação -- que deve ser compartilhável via URL e sobreviver a atualizações de página.

Exemplo de Trabalho

// app/products/page.tsx (Componente de Servidor)
import { Suspense } from "react";
import { SearchBar } from "./search-bar";
import { ProductGrid } from "./product-grid";
import { Pagination } from "./pagination";
 
type Props = {
  searchParams: Promise<{
    q?: string;
    category?: string;
    sort?: string;
    page?: string;
  }>;
};
 
export default async function ProductsPage({ searchParams }: Props) {
  const { q, category, sort, page } = await searchParams;
 
  return (
    <main className="max-w-6xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Produtos</h1>
 
      <Suspense fallback={<div>Carregando pesquisa...</div>}>
        <SearchBar />
      </Suspense>
 
      <Suspense
        key={`${q}-${category}-${sort}-${page}`}
        fallback={<div>Carregando produtos...</div>}
      >
        <ProductResults
          query={q}
          category={category}
          sort={sort ?? "newest"}
          page={Number(page) || 1}
        />
      </Suspense>
    </main>
  );
}
 
async function ProductResults({
  query,
  category,
  sort,
  page,
}: {
  query?: string;
  category?: string;
  sort: string;
  page: number;
}) {
  const { products, totalPages } = await fetchProducts({
    query,
    category,
    sort,
    page,
  });
 
  return (
    <>
      <ProductGrid products={products} />
      <Pagination currentPage={page} totalPages={totalPages} />
    </>
  );
}

// app/products/search-bar.tsx
"use client";
 
import { useSearchParams, usePathname, useRouter } from "next/navigation";
import { useTransition } from "react";
import { useDebouncedCallback } from "use-debounce";
 
export function SearchBar() {
  const searchParams = useSearchParams();
  const pathname = usePathname();
  const router = useRouter();
  const [isPending, startTransition] = useTransition();
 
  const handleSearch = useDebouncedCallback((term: string) => {
    const params = new URLSearchParams(searchParams.toString());
    if (term) {
      params.set("q", term);
      params.set("page", "1"); // reseta para a página 1 em nova pesquisa
    } else {
      params.delete("q");
    }
 
    startTransition(() => {
      router.push(`${pathname}?${params.toString()}`);
    });
  }, 300);
 
  return (
    <div className="relative mb-6">
      <input
        type="search"
        defaultValue={searchParams.get("q") ?? ""}
        onChange={(e) => handleSearch(e.target.value)}
        placeholder="Search products..."
        className="w-full border rounded px-4 py-2"
      />
      {isPending && (
        <span className="absolute right-3 top-2.5 text-gray-400">
          Searching...
        </span>
      )}
    </div>
  );
}

// app/products/pagination.tsx
"use client";
 
import { useSearchParams, usePathname } from "next/navigation";
import Link from "next/link";
 
export function Pagination({
  currentPage,
  totalPages,
}: {
  currentPage: number;
  totalPages: number;
}) {
  const searchParams = useSearchParams();
  const pathname = usePathname();
 
  function createPageUrl(page: number) {
    const params = new URLSearchParams(searchParams.toString());
    params.set("page", page.toString());
    return `${pathname}?${params.toString()}`;
  }
 
  return (
    <div className="flex gap-2 mt-6">
      {currentPage > 1 && (
        <Link href={createPageUrl(currentPage - 1)} className="px-3 py-1 border rounded">
          Previous
        </Link>
      )}
      <span className="px-3 py-1">
        Page {currentPage} of {totalPages}
      </span>
      {currentPage < totalPages && (
        <Link href={createPageUrl(currentPage + 1)} className="px-3 py-1 border rounded">
          Next
        </Link>
      )}
    </div>
  );
}

O que isso demonstra:

Leitura de searchParams no servidor como uma Promise (padrão Next.js 15+)
Uso de useSearchParams no cliente para ler e atualizar parâmetros de consulta
Debouncing da entrada de pesquisa para evitar navegações excessivas
Construção de URLs de paginação que preservam os params de pesquisa existentes
Uso de uma key em <Suspense> para reativar estados de carregamento em mudanças de parâmetro

Mergulho Profundo

Como Funciona

searchParams no lado do servidor: No App Router, os componentes de página recebem searchParams como uma prop. No Next.js 15+, isso é uma Promise que deve ser aguardada. Acessar searchParams opta a rota para renderização dinâmica.
useSearchParams no lado do cliente: Retorna uma instância URLSearchParams somente leitura. Para atualizar, construa um novo URLSearchParams, modifique-o e navegue com router.push() ou router.replace().
useSearchParams requer um limite Suspense -- Durante o pré-renderização estática, os parâmetros de pesquisa não estão disponíveis. Envolver o componente em <Suspense> fornece um fallback enquanto os parâmetros são hidratados no cliente.
O estado da URL faz parte da pilha de histórico do navegador. Usar router.push cria uma nova entrada de histórico; router.replace substitui a entrada atual (melhor para filtros e ordenação).

Variações

Usando router.replace para evitar poluir o histórico:

// Bom para filtros -- o usuário ainda pode usar o botão voltar de forma significativa
startTransition(() => {
  router.replace(`${pathname}?${params.toString()}`);
});

Lendo um único parâmetro com um padrão:

const sort = searchParams.get("sort") ?? "newest";
const page = Number(searchParams.get("page")) || 1;

Parâmetros de múltiplos valores (arrays):

// URL: ?color=red&color=blue
const colors = searchParams.getAll("color"); // ["red", "blue"]
 
// Definindo múltiplos valores
const params = new URLSearchParams();
["red", "blue"].forEach((c) => params.append("color", c));

Notas TypeScript

// Tipo searchParams do componente de servidor (Next.js 15+)
type PageProps = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};
 
// Helper de search params tipado
type ProductFilters = {
  q?: string;
  category?: string;
  sort?: "newest" | "price-asc" | "price-desc";
  page?: string;
};
 
type Props = { searchParams: Promise<ProductFilters> };

Armadilhas

searchParams opta a rota para renderização dinâmica -- Qualquer página que leia searchParams no servidor não pode ser gerada estaticamente. Correção: Se você deseja uma página estática com filtragem no lado do cliente, leia os parâmetros apenas em Componentes Cliente com useSearchParams.
useSearchParams sem Suspense causa erros de compilação -- Durante a pré-renderização, useSearchParams lança um erro porque não há parâmetros para ler. Correção: Sempre envolva componentes que usam useSearchParams em um limite <Suspense>.
Closure obsoleto com searchParams -- Em um Componente Cliente, a referência searchParams de useSearchParams() atualiza na navegação, mas closures em manipuladores de eventos podem capturar o valor antigo. Correção: Leia searchParams no momento da chamada dentro do manipulador, não fora dele.
Parâmetros de array perdem segurança de tipo -- searchParams.get("color") retorna apenas o primeiro valor, mesmo quando múltiplos existem. Correção: Use searchParams.getAll("color") para parâmetros de múltiplos valores.
searchParams é uma Promise no Next.js 15+ -- Desestruturá-lo diretamente sem await retorna um objeto Promise. Correção: Sempre use const { q } = await searchParams em Componentes de Servidor.

Alternativas

Alternativa	Use Quando	Não Use Quando
`useState` (apenas cliente)	O estado é efêmero e não precisa sobreviver à atualização	O estado deve ser compartilhável via URL
Segmentos de rota dinâmicos (`[slug]`)	O parâmetro define a identidade do recurso	O parâmetro é um filtro ou modificador
Cookies	O estado deve persistir entre sessões, mas não aparecer na URL	O estado deve ser visível e compartilhável
Biblioteca `nuqs`	Você deseja parâmetros de pesquisa tipados e validados com serialização	`useSearchParams` integrado é suficiente
Zustand com sincronização de URL	Estado complexo com múltiplos parâmetros e valores derivados	Parâmetros de URL simples chave-valor

FAQs

Por que `searchParams` é uma Promise em Componentes de Servidor Next.js 15+?

No Next.js 15+, searchParams é uma Promise que deve ser aguardada antes de acessar as propriedades
Desestruturar sem await retorna um objeto Promise, não os valores
Isso se alinha com o modelo de Componentes de Servidor assíncronos

Ler `searchParams` no servidor impede a geração estática?

Sim, acessar searchParams em um Componente de Servidor opta a rota para renderização dinâmica
A página não pode ser pré-renderizada porque os parâmetros de pesquisa só são conhecidos no momento da requisição
Se você deseja uma página estática, leia os parâmetros apenas em Componentes Cliente com useSearchParams

Por que `useSearchParams` requer um limite Suspense?

Durante a pré-renderização estática, os parâmetros de pesquisa não estão disponíveis
Sem um limite <Suspense>, a compilação falha porque useSearchParams lança um erro
O fallback do Suspense é exibido enquanto os parâmetros são hidratados no cliente

Qual a diferença entre `router.push` e `router.replace` para search params?

router.push cria uma nova entrada no histórico do navegador (o usuário pode pressionar voltar)
router.replace substitui a entrada atual do histórico (melhor para filtros e ordenação)
Use replace quando mudanças frequentes de parâmetros poluiriam a pilha de histórico

Como lidar com parâmetros de pesquisa de múltiplos valores (ex: `?color=red&color=blue`)?

// Lendo múltiplos valores
const colors = searchParams.getAll("color"); // ["red", "blue"]
 
// Definindo múltiplos valores
const params = new URLSearchParams();
["red", "blue"].forEach((c) => params.append("color", c));

searchParams.get("color") retorna apenas o primeiro valor

Como resetar a paginação para a página 1 quando a consulta de pesquisa muda?

const handleSearch = (term: string) => {
  const params = new URLSearchParams(searchParams.toString());
  if (term) {
    params.set("q", term);
    params.set("page", "1"); // reseta para a página 1
  } else {
    params.delete("q");
  }
  router.push(`${pathname}?${params.toString()}`);
};

Como tipar `searchParams` para uma página de Componente de Servidor em TypeScript?

type PageProps = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{
    [key: string]: string | string[] | undefined;
  }>;
};

Os valores podem ser string, string[] ou undefined

Qual é a armadilha de closure obsoleto com `useSearchParams`?

Closures em manipuladores de eventos podem capturar uma referência searchParams antiga
O objeto searchParams atualiza na navegação, mas o closure não o captura novamente
Leia searchParams no momento da chamada dentro do manipulador para obter o valor mais recente

Como usar uma `key` do Suspense para reativar estados de carregamento quando os parâmetros mudam?

<Suspense
  key={`${q}-${category}-${sort}-${page}`}
  fallback={<div>Loading...</div>}
>
  <ProductResults query={q} sort={sort} page={page} />
</Suspense>

Mudar a key desmonta e remonta o limite do Suspense, mostrando o fallback novamente

Quando usar `searchParams` versus segmentos de rota dinâmicos como `[slug]`?

Use segmentos dinâmicos ([slug]) quando o parâmetro define a identidade do recurso (ex: /products/shoes)
Use searchParams quando o parâmetro é um filtro ou modificador (ex: ?sort=price&page=2)
Os parâmetros de pesquisa são opcionais; segmentos dinâmicos são partes obrigatórias da URL

Como criar um helper de search params tipado para melhor segurança de tipo?

type ProductFilters = {
  q?: string;
  category?: string;
  sort?: "newest" | "price-asc" | "price-desc";
  page?: string;
};
 
type Props = { searchParams: Promise<ProductFilters> };

Isso restringe os valores possíveis e fornece autocompletar no seu IDE

Relacionados

Fetching -- Usando search params para direcionar consultas do lado do servidor
Cookies & Headers -- Outras formas de acessar dados de requisição
Client Components -- Onde useSearchParams reside
Static vs Dynamic -- Como searchParams afeta o modo de renderização

Receita

Cartão de receita de referência rápida -- pronto para copiar e colar.

// Componente de Servidor -- acesse searchParams como uma prop (Promise no Next.js 15+)
type Props = { searchParams: Promise<{ q?: string; page?: string }> };
 
export default async function Page({ searchParams }: Props) {
  const { q, page } = await searchParams;
  const results = await search(q, Number(page) || 1);
  return <ResultsList results={results} />;
}

// Componente Cliente -- hook useSearchParams
"use client";
import { useSearchParams, useRouter, usePathname } from "next/navigation";
 
export function SearchInput() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const pathname = usePathname();
 
  function handleSearch(term: string) {
    const params = new URLSearchParams(searchParams.toString());
    if (term) params.set("q", term);
    else params.delete("q");
    router.push(`${pathname}?${params.toString()}`);
  }
 
  return (
    <input
      defaultValue={searchParams.get("q") ?? ""}
      onChange={(e) => handleSearch(e.target.value)}
      placeholder="Search..."
    />
  );
}

Quando usar isso: Você precisa de estado controlado pela URL -- filtros de pesquisa, paginação, ordenação -- que deve ser compartilhável via URL e sobreviver a atualizações de página.

Exemplo de Trabalho

// app/products/page.tsx (Componente de Servidor)
import { Suspense } from "react";
import { SearchBar } from "./search-bar";
import { ProductGrid } from "./product-grid";
import { Pagination } from "./pagination";
 
type Props = {
  searchParams: Promise<{
    q?: string;
    category?: string;
    sort?: string;
    page?: string;
  }>;
};
 
export default async function ProductsPage({ searchParams }: Props) {
  const { q, category, sort, page } = await searchParams;
 
  return (
    <main className="max-w-6xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Produtos</h1>
 
      <Suspense fallback={<div>Carregando pesquisa...</div>}>
        <SearchBar />
      </Suspense>
 
      <Suspense
        key={`${q}-${category}-${sort}-${page}`}
        fallback={<div>Carregando produtos...</div>}
      >
        <ProductResults
          query={q}
          category={category}
          sort={sort ?? "newest"}
          page={Number(page) || 1}
        />
      </Suspense>
    </main>
  );
}
 
async function ProductResults({
  query,
  category,
  sort,
  page,
}: {
  query?: string;
  category?: string;
  sort: string;
  page: number;
}) {
  const { products, totalPages } = await fetchProducts({
    query,
    category,
    sort,
    page,
  });
 
  return (
    <>
      <ProductGrid products={products} />
      <Pagination currentPage={page} totalPages={totalPages} />
    </>
  );
}

// app/products/search-bar.tsx
"use client";
 
import { useSearchParams, usePathname, useRouter } from "next/navigation";
import { useTransition } from "react";
import { useDebouncedCallback } from "use-debounce";
 
export function SearchBar() {
  const searchParams = useSearchParams();
  const pathname = usePathname();
  const router = useRouter();
  const [isPending, startTransition] = useTransition();
 
  const handleSearch = useDebouncedCallback((term: string) => {
    const params = new URLSearchParams(searchParams.toString());
    if (term) {
      params.set("q", term);
      params.set("page", "1"); // reseta para a página 1 em nova pesquisa
    } else {
      params.delete("q");
    }
 
    startTransition(() => {
      router.push(`${pathname}?${params.toString()}`);
    });
  }, 300);
 
  return (
    <div className="relative mb-6">
      <input
        type="search"
        defaultValue={searchParams.get("q") ?? ""}
        onChange={(e) => handleSearch(e.target.value)}
        placeholder="Search products..."
        className="w-full border rounded px-4 py-2"
      />
      {isPending && (
        <span className="absolute right-3 top-2.5 text-gray-400">
          Searching...
        </span>
      )}
    </div>
  );
}

// app/products/pagination.tsx
"use client";
 
import { useSearchParams, usePathname } from "next/navigation";
import Link from "next/link";
 
export function Pagination({
  currentPage,
  totalPages,
}: {
  currentPage: number;
  totalPages: number;
}) {
  const searchParams = useSearchParams();
  const pathname = usePathname();
 
  function createPageUrl(page: number) {
    const params = new URLSearchParams(searchParams.toString());
    params.set("page", page.toString());
    return `${pathname}?${params.toString()}`;
  }
 
  return (
    <div className="flex gap-2 mt-6">
      {currentPage > 1 && (
        <Link href={createPageUrl(currentPage - 1)} className="px-3 py-1 border rounded">
          Previous
        </Link>
      )}
      <span className="px-3 py-1">
        Page {currentPage} of {totalPages}
      </span>
      {currentPage < totalPages && (
        <Link href={createPageUrl(currentPage + 1)} className="px-3 py-1 border rounded">
          Next
        </Link>
      )}
    </div>
  );
}

O que isso demonstra:

Leitura de searchParams no servidor como uma Promise (padrão Next.js 15+)
Uso de useSearchParams no cliente para ler e atualizar parâmetros de consulta
Debouncing da entrada de pesquisa para evitar navegações excessivas
Construção de URLs de paginação que preservam os params de pesquisa existentes
Uso de uma key em <Suspense> para reativar estados de carregamento em mudanças de parâmetro

Mergulho Profundo

Como Funciona

searchParams no lado do servidor: No App Router, os componentes de página recebem searchParams como uma prop. No Next.js 15+, isso é uma Promise que deve ser aguardada. Acessar searchParams opta a rota para renderização dinâmica.
useSearchParams no lado do cliente: Retorna uma instância URLSearchParams somente leitura. Para atualizar, construa um novo URLSearchParams, modifique-o e navegue com router.push() ou router.replace().
useSearchParams requer um limite Suspense -- Durante o pré-renderização estática, os parâmetros de pesquisa não estão disponíveis. Envolver o componente em <Suspense> fornece um fallback enquanto os parâmetros são hidratados no cliente.
O estado da URL faz parte da pilha de histórico do navegador. Usar router.push cria uma nova entrada de histórico; router.replace substitui a entrada atual (melhor para filtros e ordenação).

Variações

Usando router.replace para evitar poluir o histórico:

// Bom para filtros -- o usuário ainda pode usar o botão voltar de forma significativa
startTransition(() => {
  router.replace(`${pathname}?${params.toString()}`);
});

Lendo um único parâmetro com um padrão:

const sort = searchParams.get("sort") ?? "newest";
const page = Number(searchParams.get("page")) || 1;

Parâmetros de múltiplos valores (arrays):

// URL: ?color=red&color=blue
const colors = searchParams.getAll("color"); // ["red", "blue"]
 
// Definindo múltiplos valores
const params = new URLSearchParams();
["red", "blue"].forEach((c) => params.append("color", c));

Notas TypeScript

// Tipo searchParams do componente de servidor (Next.js 15+)
type PageProps = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};
 
// Helper de search params tipado
type ProductFilters = {
  q?: string;
  category?: string;
  sort?: "newest" | "price-asc" | "price-desc";
  page?: string;
};
 
type Props = { searchParams: Promise<ProductFilters> };

Armadilhas

searchParams opta a rota para renderização dinâmica -- Qualquer página que leia searchParams no servidor não pode ser gerada estaticamente. Correção: Se você deseja uma página estática com filtragem no lado do cliente, leia os parâmetros apenas em Componentes Cliente com useSearchParams.
useSearchParams sem Suspense causa erros de compilação -- Durante a pré-renderização, useSearchParams lança um erro porque não há parâmetros para ler. Correção: Sempre envolva componentes que usam useSearchParams em um limite <Suspense>.
Closure obsoleto com searchParams -- Em um Componente Cliente, a referência searchParams de useSearchParams() atualiza na navegação, mas closures em manipuladores de eventos podem capturar o valor antigo. Correção: Leia searchParams no momento da chamada dentro do manipulador, não fora dele.
Parâmetros de array perdem segurança de tipo -- searchParams.get("color") retorna apenas o primeiro valor, mesmo quando múltiplos existem. Correção: Use searchParams.getAll("color") para parâmetros de múltiplos valores.
searchParams é uma Promise no Next.js 15+ -- Desestruturá-lo diretamente sem await retorna um objeto Promise. Correção: Sempre use const { q } = await searchParams em Componentes de Servidor.

Alternativas

Alternativa	Use Quando	Não Use Quando
`useState` (apenas cliente)	O estado é efêmero e não precisa sobreviver à atualização	O estado deve ser compartilhável via URL
Segmentos de rota dinâmicos (`[slug]`)	O parâmetro define a identidade do recurso	O parâmetro é um filtro ou modificador
Cookies	O estado deve persistir entre sessões, mas não aparecer na URL	O estado deve ser visível e compartilhável
Biblioteca `nuqs`	Você deseja parâmetros de pesquisa tipados e validados com serialização	`useSearchParams` integrado é suficiente
Zustand com sincronização de URL	Estado complexo com múltiplos parâmetros e valores derivados	Parâmetros de URL simples chave-valor

FAQs

Por que `searchParams` é uma Promise em Componentes de Servidor Next.js 15+?

No Next.js 15+, searchParams é uma Promise que deve ser aguardada antes de acessar as propriedades
Desestruturar sem await retorna um objeto Promise, não os valores
Isso se alinha com o modelo de Componentes de Servidor assíncronos

Ler `searchParams` no servidor impede a geração estática?

Sim, acessar searchParams em um Componente de Servidor opta a rota para renderização dinâmica
A página não pode ser pré-renderizada porque os parâmetros de pesquisa só são conhecidos no momento da requisição
Se você deseja uma página estática, leia os parâmetros apenas em Componentes Cliente com useSearchParams

Por que `useSearchParams` requer um limite Suspense?

Durante a pré-renderização estática, os parâmetros de pesquisa não estão disponíveis
Sem um limite <Suspense>, a compilação falha porque useSearchParams lança um erro
O fallback do Suspense é exibido enquanto os parâmetros são hidratados no cliente

Qual a diferença entre `router.push` e `router.replace` para search params?

router.push cria uma nova entrada no histórico do navegador (o usuário pode pressionar voltar)
router.replace substitui a entrada atual do histórico (melhor para filtros e ordenação)
Use replace quando mudanças frequentes de parâmetros poluiriam a pilha de histórico

Como lidar com parâmetros de pesquisa de múltiplos valores (ex: `?color=red&color=blue`)?

// Lendo múltiplos valores
const colors = searchParams.getAll("color"); // ["red", "blue"]
 
// Definindo múltiplos valores
const params = new URLSearchParams();
["red", "blue"].forEach((c) => params.append("color", c));

searchParams.get("color") retorna apenas o primeiro valor

Como resetar a paginação para a página 1 quando a consulta de pesquisa muda?

const handleSearch = (term: string) => {
  const params = new URLSearchParams(searchParams.toString());
  if (term) {
    params.set("q", term);
    params.set("page", "1"); // reseta para a página 1
  } else {
    params.delete("q");
  }
  router.push(`${pathname}?${params.toString()}`);
};

Como tipar `searchParams` para uma página de Componente de Servidor em TypeScript?

type PageProps = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{
    [key: string]: string | string[] | undefined;
  }>;
};

Os valores podem ser string, string[] ou undefined

Qual é a armadilha de closure obsoleto com `useSearchParams`?

Closures em manipuladores de eventos podem capturar uma referência searchParams antiga
O objeto searchParams atualiza na navegação, mas o closure não o captura novamente
Leia searchParams no momento da chamada dentro do manipulador para obter o valor mais recente

Como usar uma `key` do Suspense para reativar estados de carregamento quando os parâmetros mudam?

<Suspense
  key={`${q}-${category}-${sort}-${page}`}
  fallback={<div>Loading...</div>}
>
  <ProductResults query={q} sort={sort} page={page} />
</Suspense>

Mudar a key desmonta e remonta o limite do Suspense, mostrando o fallback novamente

Quando usar `searchParams` versus segmentos de rota dinâmicos como `[slug]`?

Use segmentos dinâmicos ([slug]) quando o parâmetro define a identidade do recurso (ex: /products/shoes)
Use searchParams quando o parâmetro é um filtro ou modificador (ex: ?sort=price&page=2)
Os parâmetros de pesquisa são opcionais; segmentos dinâmicos são partes obrigatórias da URL

Como criar um helper de search params tipado para melhor segurança de tipo?

type ProductFilters = {
  q?: string;
  category?: string;
  sort?: "newest" | "price-asc" | "price-desc";
  page?: string;
};
 
type Props = { searchParams: Promise<ProductFilters> };

Isso restringe os valores possíveis e fornece autocompletar no seu IDE

Relacionados

Fetching -- Usando search params para direcionar consultas do lado do servidor
Cookies & Headers -- Outras formas de acessar dados de requisição
Client Components -- Onde useSearchParams reside
Static vs Dynamic -- Como searchParams afeta o modo de renderização

Search Params

Buscar na documentação

Search Params