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 <>Recherche : {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().

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.

Comportement

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 à une partie de la route d'être rendue statiquement tandis que la partie dynamique qui utilise useSearchParams est rendue côté client.

Nous recommandons d'encadrer le Composant Client qui utilise useSearchParams dans une limite <Suspense/>. Cela permettra aux Composants Clients situés au-dessus d'être rendus statiquement et envoyés comme partie du 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 de l'utilisation du rendu statique
  console.log(search)

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

Rendu dynamique

Si une route est rendue dynamiquement, useSearchParams sera disponible sur le serveur pendant le rendu 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 <>Recherche : {search}</>
}

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

Composants Serveur

Pages

Pour accéder aux paramètres de recherche dans les Pages (Composants Serveur), utilisez la prop searchParams.

Layouts

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.

'use client'

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

Historique des versions