Изменение query params с useRouter, usePathname и useSearchParams

Введение: Что такое параметры запроса и зачем они нужны? 🎯

Представьте, что URL-адрес страницы — это название книги, а параметры запроса (query-параметры) — это заметки на полях, которые вы оставляете. Основное название книги не меняется, но заметки помогают вам уточнить, на что именно обратить внимание: ?страница=42&глава=3. В вебе они работают точно так же.

Ключевая задача: передача дополнительной информации (сортировка, фильтры, поисковые запросы) через URL без изменения основного адреса страницы.

Пример: mysite.com/products?category=laptops&sort=price_desc

В современной разработке на Next.js (с App Router) для работы с URL используются три основных инструмента (хука):

1. Читаем URL: Знакомство с usePathname и useSearchParams 📖

Хук usePathname — Где мы находимся?

У этого хука одна простая задача: получить текущий путь в адресной строке без домена и без query-параметров.

Пример: Если полный URL — https://example.com/profile/123?active=true, то usePathname вернет только /profile/123.

import { usePathname } from "next/navigation"
 
function CurrentPath() {
  const pathname = usePathname() // Получаем '/profile/123'
 
  return <div>Текущий путь: {pathname}</div>
}

Хук useSearchParams — Что написано в "заметках на полях"?

Но как же изменять параметры? Прямо — никак. Потребуется другой подход.🤔

2. Главный секрет: изменение URL через навигацию🧩

Основная идея: изменение query-параметров — это не модификация текущего URL, а перенаправление на новый адрес. Даже если адрес отличается одним символом в параметрах, для Next.js это переход на "другую" страницу.

Два способа выполнения перехода:

3. Собираем всё вместе: практический рецепт 🍳

Это официально рекомендованный подход из документации Next.js для управления состоянием URL в App Router.

1. Шаг 1: Получаем "ингредиенты". Внутри вашего компонента импортируем и вызываем все три хука: useRouter, usePathname и useSearchParams.

2. Шаг 2: Готовим новые параметры. С помощью встроенного в браузер конструктора URLSearchParams мы создаем новый, изменяемый набор параметров.

• Почему new URLSearchParams(searchParams.toString())? Хук useSearchParams возвращает read-only (только для чтения) объект. Чтобы создать его изменяемую копию, мы сначала превращаем текущие параметры в строку (searchParams.toString()), а затем передаем эту строку в конструктор new URLSearchParams(). В результате мы получаем новый, полностью управляемый объект.

3. Шаг 3: Собираем новый URL. Мы объединяем pathname (из usePathname) с новой строкой параметров, чтобы получить полный целевой адрес.

4. Шаг 4: Выполняем переход. Используем полученный URL в <Link> или передаем его в router.push.

Пример 1: Изменение URL с помощью кнопки и router.push

Представим, что мы хотим добавить параметр title=book к текущему URL по нажатию на кнопку. Следуя лучшим практикам, вынесем логику создания URL в отдельную функцию.

import { usePathname, useRouter, useSearchParams } from "next/navigation"
import { useCallback } from "react"
import styles from "./header.module.css"
 
export const Header = () => {
  const router = useRouter()
  const searchParams = useSearchParams()
  const pathname = usePathname()
 
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)
      return params.toString()
    },
    [searchParams],
  )
 
  return (
    <nav className={styles.navigation}>
      <button
        onClick={() => {
          router.push(pathname + "?" + createQueryString("sort", "asc"))
        }}
      >
        ASC
      </button>
      <ul>
        <li>
          <button onClick={() => router.push("/", { scroll: false })} className={styles.link}>
            Main
          </button>
        </li>
        <li>
          <button
            onClick={() => router.push("/profile", { scroll: false })}
            className={styles.link}
          >
            Profile
          </button>
        </li>
        <li>
          <button
            onClick={() => router.push("/profile/123", { scroll: false })}
            className={styles.link}
          >
            Profile 123
          </button>
        </li>
      </ul>
    </nav>
  )
}

При нажатии на кнопку произойдет редирект на тот же путь, но с добавленным ?title=book.

Пример 2: Изменение URL с помощью ссылки <Link>

Результат будет абсолютно идентичным, но реализация будет декларативной. Мы заранее готовим URL для ссылки, используя ту же логику.

import { usePathname, useRouter, useSearchParams } from "next/navigation"
import { useCallback } from "react"
import styles from "./header.module.css"
 
export const Header = () => {
  const router = useRouter()
  const searchParams = useSearchParams()
  const pathname = usePathname()
 
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)
      return params.toString()
    },
    [searchParams],
  )
 
  return (
    <nav className={styles.navigation}>
      <Link href={pathname + "?" + createQueryString("title", "book")}>book</Link>
      <ul>
        <li>
          <button onClick={() => router.push("/", { scroll: false })} className={styles.link}>
            Main
          </button>
        </li>
        <li>
          <button
            onClick={() => router.push("/profile", { scroll: false })}
            className={styles.link}
          >
            Profile
          </button>
        </li>
        <li>
          <button
            onClick={() => router.push("/profile/123", { scroll: false })}
            className={styles.link}
          >
            Profile 123
          </button>
        </li>
      </ul>
    </nav>
  )
}

Этот подход более предпочтителен для простой навигации, так как он семантически верный и не требует JavaScript для обработки клика.

4. Ключевые выводы 🎓

Давайте подведем итоги и закрепим материал.

1. 📖 Хук useSearchParams только читает параметры из URL. Он не предназначен для их изменения.
2. ✏️ Изменение query-параметров всегда происходит через перенаправление с помощью компонента <Link> или метода router.push.
3. 🧩 Связка хуков useRouter, usePathname и useSearchParams является стандартным и рекомендуемым способом для динамического управления URL в современных приложениях на Next.js.