useSearchParams для query-параметров

useSearchParams — это хук, предоставляемый библиотекой React Router, который позволяет удобно работать с query-параметрами URL. Он возвращает массив из двух элементов: объекта URLSearchParams и функции для обновления этих параметров.

const [searchParams, setSearchParams] = useSearchParams();
  • searchParams — объект URLSearchParams, с помощью которого можно получать значения query-параметров.
  • setSearchParams — функция для изменения query-параметров, которая обновляет URL и инициирует повторный рендер компонента.

Получение значений query-параметров

Для чтения конкретного параметра используется метод get объекта URLSearchParams.

const page = searchParams.get('page'); // получает значение параметра 'page'
const sort = searchParams.get('sort'); // получает значение параметра 'sort'

Если параметр отсутствует, get вернет null. Можно использовать стандартные методы URLSearchParams:

  • has('param') — проверяет наличие параметра.
  • getAll('param') — возвращает массив значений параметра, если он повторяется.
  • entries(), keys(), values() — позволяют итерировать параметры.

Установка и обновление query-параметров

setSearchParams может принимать как объект, так и экземпляр URLSearchParams.

Пример с объектом:

setSearchParams({ page: '2', sort: 'asc' });

Это создаст URL вида /current-path?page=2&sort=asc.

Пример с URLSearchParams:

const params = new URLSearchParams();
params.set('page', '3');
params.set('filter', 'active');
setSearchParams(params);

Важно: при использовании объекта предыдущие query-параметры, которых нет в новом объекте, будут удалены. Если нужно сохранить существующие параметры и изменить только некоторые, сначала нужно клонировать searchParams:

const params = new URLSearchParams(searchParams);
params.set('page', '4');
setSearchParams(params);

Работа с несколькими значениями одного параметра

URLSearchParams поддерживает несколько значений одного ключа:

searchParams.append('tag', 'react');
searchParams.append('tag', 'router');

Для получения всех значений используется метод getAll:

const tags = searchParams.getAll('tag'); // ['react', 'router']

Для обновления таких параметров рекомендуется создавать новый экземпляр URLSearchParams и использовать методы delete и append:

const params = new URLSearchParams();
params.append('tag', 'javascript');
params.append('tag', 'web');
setSearchParams(params);

Синхронизация состояния с query-параметрами

useSearchParams удобно использовать для синхронизации состояния компонентов с URL. Например, пагинация:

const [searchParams, setSearchParams] = useSearchParams();
const currentPage = parseInt(searchParams.get('page') || '1', 10);

const goToNextPage = () => {
  const params = new URLSearchParams(searchParams);
  params.set('page', (currentPage + 1).toString());
  setSearchParams(params);
};

Такое решение позволяет:

  • Поддерживать навигацию по истории браузера.
  • Сохранять состояние при обновлении страницы.
  • Делать URL “читаемым” и удобным для ссылок.

Управление состоянием фильтров и сортировки

Для сложных интерфейсов с фильтрацией и сортировкой query-параметры служат естественным способом хранения состояния.

const filters = {
  category: searchParams.get('category') || 'all',
  sort: searchParams.get('sort') || 'desc',
};

const updateFilter = (key, value) => {
  const params = new URLSearchParams(searchParams);
  params.set(key, value);
  setSearchParams(params);
};

Пример использования в UI:

<button onCl ick={() => updateFilter('category', 'books')}>Книги</button>
<button onCl ick={() => updateFilter('sort', 'asc')}>По возрастанию</button>

Каждое изменение обновляет URL и рендерит компонент с новым состоянием фильтров.

Особенности работы с React Router

  • useSearchParams автоматически следит за изменением URL, поэтому при навигации через кнопки браузера состояние всегда синхронизировано.
  • Хук полностью совместим с Link и NavLink. Параметры можно передавать прямо в to:
<Link to={{ pathname: '/products', search: '?page=2&sort=asc' }}>Страница 2</Link>
  • Для асинхронной загрузки данных по query-параметрам удобно использовать useEffect:
useEffect(() => {
  const page = searchParams.get('page') || '1';
  fetchData({ page });
}, [searchParams]);

Преимущества использования useSearchParams

  • Прямой доступ к query-параметрам без парсинга URL вручную.
  • Синхронизация состояния с URL.
  • Удобство для навигации, пагинации, фильтров и сортировки.
  • Полная совместимость с React Router и историей браузера.
  • Чистый код без лишнего управления состоянием через useState.

useSearchParams превращает работу с query-параметрами в структурированный и предсказуемый процесс, делая URL частью состояния приложения и упрощая управление динамическими интерфейсами.

Оглавление