useSearchParams

useSearchParams — это хук Клиентского Компонента (Client Component), который позволяет читать строку запроса текущего 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: {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: {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)

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

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

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

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

  return <>Search: {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: {search}</>
}

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

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

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 <>placeholder</>
}

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

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

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

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

Например:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

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

  return <>Search: {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: {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>
    </>
  )
}

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

Страницы (Pages)

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

В отличие от Страниц, Макеты (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)
      params.set(name, value)

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

  return (
    <>
      <p>Sort By</p>

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

      {/* используя <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        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>Sort By</p>

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

      {/* используя <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

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

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

On this page