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 <>Search: {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 obtener todos los valores

• URLSearchParams.has(): Devuelve un valor booleano que indica si existe el parámetro dado. Por ejemplo:

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

• Aprende más sobre otros métodos de solo lectura de URLSearchParams, incluyendo getAll(), keys(), values(), entries(), forEach(), y toString().

Nota 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 se pueden conocer durante el pre-renderizado de una página que no usa getServerSideProps.

Comportamiento

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 lado del cliente.

Esto permite que una 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 cuando se use renderizado estático
  console.log(search)

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

Renderizado Dinámico

Si una ruta se renderiza dinámicamente, useSearchParams estará disponible en el servidor durante el renderizado inicial del servidor 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 <>Search: {search}</>
}

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

Componentes Servidor

Páginas

Para acceder a los parámetros de búsqueda en Páginas (Componentes Servidor), usa la prop searchParams.

Layouts

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 llevar a 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 realizar una navegación, la página page.js actual recibirá una prop searchParams actualizada.

'use client'

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

Historial de Versiones