useSearchParams

useSearchParams es un hook de Componente Cliente que permite leer la cadena de consulta (query string) de la URL actual.

useSearchParams devuelve una versión de solo lectura de la interfaz 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 <>Buscar: {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 <>Buscar: {search}</>
}

Parámetros

const searchParams = useSearchParams()

useSearchParams no acepta ningún parámetro.

Retorno

useSearchParams devuelve una versión de solo lectura de la interfaz URLSearchParams, que incluye métodos útiles para leer la cadena de consulta de la URL:

URLSearchParams.get(): Devuelve el primer valor asociado al parámetro de búsqueda. Por ejemplo:

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - usa getAll() para todos los valores
URLSearchParams.has(): Devuelve un valor booleano indicando si existe el parámetro. Por ejemplo:

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
Más información sobre otros métodos de solo lectura de URLSearchParams, incluyendo getAll(), keys(), values(), entries(), forEach(), y toString().

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - usa `getAll()` para todos los valores

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

Importante:

useSearchParams es un hook de Componente Cliente y no es compatible con Componentes Servidor para evitar valores obsoletos durante el renderizado parcial.

Si una aplicación incluye el directorio /pages, useSearchParams devolverá ReadonlyURLSearchParams | null. El valor null es para compatibilidad durante la migración, ya que los parámetros de búsqueda no pueden conocerse durante el pre-renderizado de una página que no usa getServerSideProps.

Renderizado estático

Si una ruta se renderiza estáticamente, llamar a useSearchParams hará que el árbol de componentes cliente hasta el límite Suspense más cercano se renderice en el cliente.

Esto permite que parte de la ruta se renderice estáticamente mientras la parte dinámica que usa useSearchParams se renderiza en el cliente.

Recomendamos envolver el Componente Cliente que usa useSearchParams en un límite <Suspense/>. Esto permitirá que los Componentes Cliente superiores se rendericen estáticamente y se envíen como parte del HTML inicial. Ejemplo.

Por ejemplo:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Esto no se registrará en el servidor con renderizado estático
  console.log(search)

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Esto no se registrará en el servidor con renderizado estático
  console.log(search)

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

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

// Este componente pasado como fallback al límite Suspense
// se renderizará en lugar de la barra de búsqueda en el HTML inicial.
// Cuando el valor esté disponible durante la hidratación de React,
// el fallback será reemplazado por el componente `<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'

// Este componente pasado como fallback al límite Suspense
// se renderizará en lugar de la barra de búsqueda en el HTML inicial.
// Cuando el valor esté disponible durante la hidratación de React,
// el fallback será reemplazado por el componente `<SearchBar>`.
function SearchBarFallback() {
  return <>placeholder</>
}

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

Comportamiento

Renderizado dinámico

Si una ruta se renderiza dinámicamente, useSearchParams estará disponible en el servidor durante el renderizado inicial del Componente Cliente.

Por ejemplo:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Esto se registrará en el servidor durante el renderizado inicial
  // y en el cliente en navegaciones posteriores.
  console.log(search)

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Esto se registrará en el servidor durante el renderizado inicial
  // y en el cliente en navegaciones posteriores.
  console.log(search)

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

Importante: Configurar la opción dynamic en segmentos de ruta como force-dynamic puede usarse para forzar el renderizado dinámico.

A diferencia de las Páginas, los Layouts (Componentes Servidor) no reciben la prop searchParams. Esto se debe a que un layout compartido no se vuelve a renderizar durante la navegación, lo que podría generar searchParams obsoletos entre navegaciones. Ver explicación detallada.

En su lugar, usa la prop searchParams de la Página o el hook useSearchParams en un Componente Cliente, que se vuelve a renderizar en el cliente con los searchParams más recientes.

Ejemplos

Actualizando `searchParams`

Puedes usar useRouter o Link para establecer nuevos searchParams. Después de una navegación, la page.js actual recibirá una prop searchParams actualizada.

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

  // Obtén una nueva cadena searchParams fusionando los
  // searchParams actuales con un par clave/valor proporcionado
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)

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

  return (
    <>
      <p>Ordenar por</p>

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

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

  // Obtén una nueva cadena searchParams fusionando los
  // searchParams actuales con un par clave/valor proporcionado
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Ordenar por</p>

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

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

Historial de versiones

Versión	Cambios
`v13.0.0`	Se introdujo `useSearchParams`.

On this page