useSearchParams

useSearchParams ist ein Client Component-Hook, der es ermöglicht, die Query-Parameter der aktuellen URL auszulesen.

useSearchParams gibt eine schreibgeschützte Version der URLSearchParams-Schnittstelle zurück.

'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 <>Suche: {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 <>Suche: {search}</>
}

Parameter

const searchParams = useSearchParams()

useSearchParams benötigt keine Parameter.

Rückgabewerte

useSearchParams gibt eine schreibgeschützte Version der URLSearchParams-Schnittstelle zurück, die Hilfsmethoden zum Auslesen der Query-Parameter der URL enthält:

URLSearchParams.get(): Gibt den ersten Wert zurück, der mit dem Suchparameter verknüpft ist. Beispiel:

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - verwenden Sie getAll() für alle Werte
URLSearchParams.has(): Gibt einen booleschen Wert zurück, der anzeigt, ob der Parameter existiert. Beispiel:

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
Weitere Informationen zu anderen schreibgeschützten Methoden von URLSearchParams, einschließlich getAll(), keys(), values(), entries(), forEach() und toString().

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - verwenden Sie `getAll()` für alle Werte

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

Wichtig zu wissen:

useSearchParams ist ein Client Component-Hook und wird in Server Components nicht unterstützt, um veraltete Werte während des partiellen Rendering zu vermeiden.

Falls eine Anwendung das /pages-Verzeichnis enthält, gibt useSearchParams ReadonlyURLSearchParams | null zurück. Der null-Wert dient der Kompatibilität während der Migration, da Query-Parameter während des Pre-Rendering einer Seite, die getServerSideProps nicht verwendet, nicht bekannt sein können.

Statisches Rendering

Wenn eine Route statisch gerendert wird, führt der Aufruf von useSearchParams dazu, dass der Client Component-Baum bis zur nächsten Suspense-Grenze clientseitig gerendert wird.

Dies ermöglicht es, einen Teil der Route statisch zu rendern, während der dynamische Teil, der useSearchParams verwendet, clientseitig gerendert wird.

Wir empfehlen, die Client Component, die useSearchParams verwendet, in eine <Suspense/>-Grenze zu wrappen. Dadurch können alle darüber liegenden Client Components statisch gerendert und als Teil des initialen HTML gesendet werden. Beispiel.

Beispiel:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird beim statischen Rendering nicht auf dem Server geloggt
  console.log(search)

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird beim statischen Rendering nicht auf dem Server geloggt
  console.log(search)

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

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

// Diese Komponente wird als Fallback für die Suspense-Grenze
// anstelle der Suchleiste im initialen HTML gerendert.
// Sobald der Wert während der React-Hydration verfügbar ist,
// wird der Fallback durch die `<SearchBar>`-Komponente ersetzt.
function SearchBarFallback() {
  return <>Platzhalter</>
}

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

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

// Diese Komponente wird als Fallback für die Suspense-Grenze
// anstelle der Suchleiste im initialen HTML gerendert.
// Sobald der Wert während der React-Hydration verfügbar ist,
// wird der Fallback durch die `<SearchBar>`-Komponente ersetzt.
function SearchBarFallback() {
  return <>Platzhalter</>
}

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

Verhalten

Dynamisches Rendering

Wenn eine Route dynamisch gerendert wird, ist useSearchParams während des initialen Server-Rendering der Client Component verfügbar.

Beispiel:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird während des initialen Server-Rendering geloggt
  // und clientseitig bei nachfolgenden Navigationen.
  console.log(search)

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird während des initialen Server-Rendering geloggt
  // und clientseitig bei nachfolgenden Navigationen.
  console.log(search)

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

Wichtig zu wissen: Die Option dynamic route segment config kann auf force-dynamic gesetzt werden, um dynamisches Rendering zu erzwingen.

Im Gegensatz zu Seiten erhalten Layouts (Server Components) keine searchParams-Prop. Dies liegt daran, dass ein gemeinsames Layout während der Navigation nicht neu gerendert wird, was zu veralteten searchParams zwischen Navigationen führen könnte. Siehe detaillierte Erklärung.

Verwenden Sie stattdessen die searchParams-Prop der Page oder den useSearchParams-Hook in einer Client Component, die clientseitig mit den aktuellsten searchParams neu gerendert wird.

Beispiele

Aktualisieren von `searchParams`

Sie können useRouter oder Link verwenden, um neue searchParams zu setzen. Nach einer Navigation erhält die aktuelle page.js eine aktualisierte searchParams-Prop.

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

  // Erzeugt einen neuen searchParams-String durch Zusammenführen
  // der aktuellen searchParams mit einem bereitgestellten Schlüssel/Wert-Paar
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)

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

  return (
    <>
      <p>Sortieren nach</p>

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

      {/* Verwendung von <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()

  // Erzeugt einen neuen searchParams-String durch Zusammenführen
  // der aktuellen searchParams mit einem bereitgestellten Schlüssel/Wert-Paar
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Sortieren nach</p>

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

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

Versionsverlauf

Version	Änderungen
`v13.0.0`	`useSearchParams` eingeführt.

On this page