useSearchParams

useSearchParams est un hook de Composant Client qui permet de lire la chaîne de requête de l'URL actuelle.

useSearchParams retourne une version en lecture seule de l'interface 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}</>
}

Paramètres

const searchParams = useSearchParams()

useSearchParams ne prend aucun paramètre.

Valeur retournée

useSearchParams retourne une version en lecture seule de l'interface URLSearchParams, qui inclut des méthodes utilitaires pour lire la chaîne de requête de l'URL :

URLSearchParams.get() : Retourne la première valeur associée au paramètre de recherche. Par exemple :

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - utilisez getAll() pour toutes les valeurs
URLSearchParams.has() : Retourne une valeur booléenne indiquant si le paramètre donné existe. Par exemple :

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
Apprenez-en plus sur les autres méthodes en lecture seule de URLSearchParams, incluant getAll(), keys(), values(), entries(), forEach(), et toString().

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - utilisez `getAll()` pour toutes les valeurs

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

Bon à savoir :

useSearchParams est un hook de Composant Client et n'est pas supporté dans les Composants Serveur pour éviter des valeurs obsolètes pendant le rendu partiel.

Si une application inclut le répertoire /pages, useSearchParams retournera ReadonlyURLSearchParams | null. La valeur null est pour la compatibilité pendant la migration car les paramètres de recherche ne peuvent pas être connus pendant le pré-rendu d'une page qui n'utilise pas getServerSideProps.

Rendu statique

Si une route est rendue statiquement, l'appel à useSearchParams entraînera le rendu côté client de l'arborescence des composants jusqu'à la limite Suspense la plus proche.

Cela permet qu'une partie de la route soit rendue statiquement tandis que la partie dynamique utilisant useSearchParams est rendue côté client.

Nous recommandons d'encadrer le Composant Client utilisant useSearchParams dans une limite <Suspense/>. Cela permettra aux Composants Clients situés au-dessus d'être rendus statiquement et envoyés dans le HTML initial. Exemple.

Par exemple :

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Ceci ne sera pas enregistré sur le serveur lors du rendu statique
  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')

  // Ceci ne sera pas enregistré sur le serveur lors du rendu statique
  console.log(search)

  return <>Search: {search}</>
}

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

// Ce composant passé comme fallback à la limite Suspense
// sera rendu à la place de la barre de recherche dans le HTML initial.
// Quand la valeur est disponible pendant l'hydratation de React, le fallback
// sera remplacé par le composant `<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'

// Ce composant passé comme fallback à la limite Suspense
// sera rendu à la place de la barre de recherche dans le HTML initial.
// Quand la valeur est disponible pendant l'hydratation de React, le fallback
// sera remplacé par le composant `<SearchBar>`.
function SearchBarFallback() {
  return <>placeholder</>
}

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

Comportement

Rendu dynamique

Si une route est rendue dynamiquement, useSearchParams sera disponible sur le serveur pendant le rendu serveur initial du Composant Client.

Par exemple :

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Ceci sera enregistré sur le serveur pendant le rendu initial
  // et sur le client lors des navigations suivantes.
  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')

  // Ceci sera enregistré sur le serveur pendant le rendu initial
  // et sur le client lors des navigations suivantes.
  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>
    </>
  )
}

Bon à savoir : Définir l'option dynamic de configuration des segments de route à force-dynamic peut être utilisé pour forcer le rendu dynamique.

Contrairement aux Pages, les Layouts (Composants Serveur) ne reçoivent pas la prop searchParams. C'est parce qu'un layout partagé n'est pas re-rendu pendant la navigation, ce qui pourrait entraîner des searchParams obsolètes entre les navigations. Voir explication détaillée.

À la place, utilisez la prop searchParams de la Page ou le hook useSearchParams dans un Composant Client, qui est re-rendu côté client avec les derniers searchParams.

Exemples

Mise à jour de `searchParams`

Vous pouvez utiliser useRouter ou Link pour définir de nouveaux searchParams. Après une navigation, la page.js actuelle recevra une prop searchParams mise à jour.

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

  // Obtenez une nouvelle chaîne searchParams en fusionnant les
  // searchParams actuels avec une paire clé/valeur fournie
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)

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

  return (
    <>
      <p>Trier par</p>

      {/* en utilisant useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      {/* en utilisant <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()

  // Obtenez une nouvelle chaîne searchParams en fusionnant les
  // searchParams actuels avec une paire clé/valeur fournie
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Trier par</p>

      {/* en utilisant useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      {/* en utilisant <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

Historique des versions

Version	Changements
`v13.0.0`	`useSearchParams` introduit.

On this page