useSearchParams

useSearchParams — это хук Клиентского Компонента (Client Component), который позволяет читать строку запроса (query string) текущего URL.

useSearchParams возвращает только для чтения версию интерфейса URLSearchParams.

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // URL -> `/dashboard?search=my-project`
  // `search` -> 'my-project'
  return <>Поиск: {search}</>
}

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // URL -> `/dashboard?search=my-project`
  // `search` -> 'my-project'
  return <>Поиск: {search}</>
}

Параметры

const searchParams = useSearchParams()

useSearchParams не принимает параметров.

Возвращаемое значение

useSearchParams возвращает только для чтения версию интерфейса URLSearchParams, которая включает методы для чтения строки запроса URL:

URLSearchParams.get(): Возвращает первое значение, связанное с параметром поиска. Например:

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - используйте getAll() для получения всех значений
URLSearchParams.has(): Возвращает булево значение, указывающее на наличие параметра. Например:

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
Узнайте больше о других методах только для чтения URLSearchParams, включая getAll(), keys(), values(), entries(), forEach(), и toString().

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - используйте `getAll()` для получения всех значений

URL	`searchParams.has("a")`
`/dashboard?a=1`	`true`
`/dashboard?b=3`	`false`

Полезно знать:

useSearchParams — это хук Клиентского Компонента (Client Component) и не поддерживается в Серверных Компонентах (Server Components), чтобы избежать устаревших значений во время частичного рендеринга (partial rendering).

Если приложение включает директорию /pages, useSearchParams вернёт ReadonlyURLSearchParams | null. Значение null добавлено для совместимости во время миграции, так как параметры поиска не могут быть известны во время предварительного рендеринга страницы, не использующей getServerSideProps.

Статический рендеринг (Static Rendering)

Если маршрут рендерится статически, вызов useSearchParams приведёт к клиентскому рендерингу дерева компонентов вплоть до ближайшей границы Suspense.

Это позволяет части маршрута рендериться статически, в то время как динамическая часть, использующая useSearchParams, рендерится на стороне клиента.

Рекомендуется обернуть Клиентский Компонент, использующий useSearchParams, в границу <Suspense/>. Это позволит статически отрендерить Клиентские Компоненты выше и отправить их как часть начального HTML. Пример.

Например:

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // Это не будет залогировано на сервере при статическом рендеринге
  console.log(search)

  return <>Поиск: {search}</>
}

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // Это не будет залогировано на сервере при статическом рендеринге
  console.log(search)

  return <>Поиск: {search}</>
}

import { Suspense } from 'react'
import SearchBar from './search-bar'

// Этот компонент, переданный как fallback для границы Suspense,
// будет отрендерен вместо строки поиска в начальном HTML.
// Когда значение станет доступным во время гидратации React,
// fallback будет заменён компонентом `<SearchBar>`.
function SearchBarFallback() {
  return <>заполнитель</>
}

export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

import { Suspense } from 'react'
import SearchBar from './search-bar'

// Этот компонент, переданный как fallback для границы Suspense,
// будет отрендерен вместо строки поиска в начальном HTML.
// Когда значение станет доступным во время гидратации React,
// fallback будет заменён компонентом `<SearchBar>`.
function SearchBarFallback() {
  return <>заполнитель</>
}

export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

Поведение

Динамический рендеринг (Dynamic Rendering)

Если маршрут рендерится динамически, useSearchParams будет доступен на сервере во время начального серверного рендеринга Клиентского Компонента.

Например:

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // Это будет залогировано на сервере во время начального рендеринга
  // и на клиенте при последующих навигациях.
  console.log(search)

  return <>Поиск: {search}</>
}

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // Это будет залогировано на сервере во время начального рендеринга
  // и на клиенте при последующих навигациях.
  console.log(search)

  return <>Поиск: {search}</>
}

import SearchBar from './search-bar'

export const dynamic = 'force-dynamic'

export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

import SearchBar from './search-bar'

export const dynamic = 'force-dynamic'

export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

Полезно знать: Установка опции dynamic для сегмента маршрута в force-dynamic может использоваться для принудительного динамического рендеринга.

Серверные Компоненты (Server Components)

Страницы (Pages)

Для доступа к параметрам поиска в Страницах (Pages) (Серверных Компонентах) используйте проп searchParams.

Макеты (Layouts)

В отличие от Страниц, Макеты (Layouts) (Серверные Компоненты) не получают проп searchParams. Это связано с тем, что общий макет не перерендеривается во время навигации, что может привести к устаревшим searchParams между переходами. Подробнее в объяснении.

Вместо этого используйте проп searchParams Страницы или хук useSearchParams в Клиентском Компоненте, который перерендеривается на клиенте с актуальными searchParams.

Примеры

Обновление `searchParams`

Вы можете использовать useRouter или Link для установки новых searchParams. После выполнения навигации текущая page.js получит обновлённый searchParams проп.

export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // Получение новой строки searchParams путём объединения текущих
  // searchParams с переданной парой ключ/значение
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)

      return params.toString()
    },
    [searchParams]
  )

  return (
    <>
      <p>Сортировать по</p>

      {/* используя useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        По возрастанию
      </button>

      {/* используя <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        По убыванию
      </Link>
    </>
  )
}

export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // Получение новой строки searchParams путём объединения текущих
  // searchParams с переданной парой ключ/значение
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

      return params.toString()
    },
    [searchParams]
  )

  return (
    <>
      <p>Сортировать по</p>

      {/* используя useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        По возрастанию
      </button>

      {/* используя <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        По убыванию
      </Link>
    </>
  )
}

История версий

Версия	Изменения
`v13.0.0`	Добавлен `useSearchParams`.

On this page