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 dado. 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 por 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 use getServerSideProps.

Comportamiento

Renderizado Estático

Si una ruta tiene renderizado estático, llamar a useSearchParams() hará que el árbol hasta el límite más cercano de Suspense se renderice en el lado del cliente.

Esto permite que una parte de la página se renderice estáticamente mientras la parte dinámica que usa searchParams se renderiza en el cliente.

Puedes reducir la porción de la ruta que se renderiza en el cliente envolviendo el componente que usa useSearchParams en un límite Suspense. 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>
    </>
  )
}

Renderizado Dinámico

Si una ruta tiene renderizado dinámico, useSearchParams estará disponible en el servidor durante el renderizado inicial del Componente Cliente.

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

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

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