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

Parameter

const searchParams = useSearchParams()

useSearchParams benötigt keine Parameter.

Rückgabewert

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 angibt, ob der Parameter existiert. Beispiel:

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
Erfahren Sie mehr über andere schreibgeschützte 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`

Wissenswert:

useSearchParams ist ein Client Component-Hook und wird nicht in Server Components unterstützt, um veraltete Werte während des partiellen Renderings 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-Renderings einer Seite, die getServerSideProps nicht verwendet, nicht bekannt sein können.

Verhalten

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 client-seitig gerendert wird.

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

Wir empfehlen, die Client Component, die useSearchParams verwendet, in eine <Suspense/>-Grenze zu wrappen. Dadurch können alle darüberliegenden 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 nicht auf dem Server protokolliert, wenn statisches Rendering verwendet wird
  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')

  // Dies wird nicht auf dem Server protokolliert, wenn statisches Rendering verwendet wird
  console.log(search)

  return <>Search: {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 <>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'

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

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

Dynamisches Rendering

Wenn eine Route dynamisch gerendert wird, ist useSearchParams auf dem Server während des initialen Server-Renderings 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 auf dem Server während des initialen Renderings
  // und auf dem Client bei nachfolgenden Navigationen protokolliert.
  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')

  // Dies wird auf dem Server während des initialen Renderings
  // und auf dem Client bei nachfolgenden Navigationen protokolliert.
  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>
    </>
  )
}

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

Im Gegensatz zu Pages 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 auf dem Client 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.

'use client'

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

  // Erstellt 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>Sort By</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>
    </>
  )
}

'use client'

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

  // Erstellt 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>Sort By</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