re:re:actable
Урок 102 минуты чтения

useSearchParams и как получить query-параметры из URL

На этой странице
Кратко

Query-параметры — часть URL после ?: /products?category=phones&page=2. В React Router их читают и меняют хуком useSearchParams(), который возвращает объект URLSearchParams и функцию обновления. Изменение параметров создает новую запись в истории и вызывает ререндер, поэтому в URL удобно хранить фильтры, сортировку, поиск и пагинацию — ими можно поделиться ссылкой, и они переживут перезагрузку.

Вопрос

Что делает useSearchParams()? Как получить и изменить query-параметры из URL?

Чтение

import { useSearchParams } from "react-router";
 
function Products() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const category = searchParams.get("category") ?? "all";  // строка или null
  const page = Number(searchParams.get("page") ?? 1);      // всегда строка — приводим тип
  const tags = searchParams.getAll("tag");                 // ?tag=a&tag=b → ["a", "b"]
 
  return <ProductList category={category} page={page} tags={tags} />;
}

Изменение

// заменить все параметры
setSearchParams({ category: "phones", page: "1" });
 
// обновить один, сохранив остальные
setSearchParams((prev) => {
  prev.set("page", String(page + 1));
  return prev;
});
 
// удалить параметр, не создавая новую запись в истории
setSearchParams(
  (prev) => {
    prev.delete("tag");
    return prev;
  },
  { replace: true },
);

Без React Router

const params = new URLSearchParams(window.location.search);
params.get("category");
 
// обновить URL без перезагрузки
const url = new URL(window.location.href);
url.searchParams.set("page", "2");
history.pushState(null, "", url);

Но такой подход не вызывает ререндер — React не узнает об изменении.

Path-параметры и query-параметры

Path (useParams)Query (useSearchParams)
Пример/users/:id → /users/42/users?sort=name
Для чегоидентификатор ресурсафильтры, сортировка, поиск, страница
Обязательностьчасть маршрутанеобязательные
Несколько значенийнетда (getAll)

Что важно помнить

  • Все значения — строки: парсите числа и булевы, валидируйте (например, через Zod).
  • Для поиска с вводом используйте replace: true и debounce, чтобы не засорять историю.
  • В Next.js App Router аналог — useSearchParams из next/navigation (только чтение) и searchParams в page.
  • Сложное состояние фильтров удобно синхронизировать с URL библиотекой nuqs.

Мини-шпаргалка

const [params, setParams] = useSearchParams(). Чтение — params.get("x"), массив — getAll. Запись — setParams(obj) или setParams(prev => ...). Значения — строки. В URL — фильтры, сортировка, страница.

Документация

React Router: useSearchParams, MDN: URLSearchParams, Next.js: useSearchParams.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам