logoNext.js 日本語
ドキュメントブログ学習
はじめに/API リファレンス/関数/useSearchParams

useSearchParams

useSearchParams は、現在の URL のクエリ文字列を読み取ることができるクライアントコンポーネント用のフックです。

useSearchParams は、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}</>
}
'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}</>
}

パラメータ

const searchParams = useSearchParams()

useSearchParams はパラメータを取りません。

戻り値

useSearchParams は、URL のクエリ文字列を読み取るためのユーティリティメソッドを含む URLSearchParams インターフェースの読み取り専用バージョンを返します:

  • URLSearchParams.get(): 検索パラメータに関連付けられた最初の値を返します。例:

    URLsearchParams.get("a")
    /dashboard?a=1'1'
    /dashboard?a=''
    /dashboard?b=3null
    /dashboard?a=1&a=2'1' - すべての値を取得するには getAll() を使用

  • URLSearchParams.has(): 指定されたパラメータが存在するかどうかを示すブール値を返します。例:

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

  • getAll(), keys(), values(), entries(), forEach(), toString() など、URLSearchParams の他の読み取り専用メソッドについても学べます。

知っておくと便利:

  • useSearchParams はクライアントコンポーネント用のフックであり、部分レンダリング時に古い値が表示されるのを防ぐため、サーバーコンポーネントではサポートされていません。
  • アプリケーションに /pages ディレクトリが含まれている場合、useSearchParams は ReadonlyURLSearchParams | null を返します。null 値は移行時の互換性のためで、getServerSideProps を使用しないページのプリレンダリング時には検索パラメータが認識できないためです。

動作

静的レンダリング

ルートが静的レンダリングされている場合、useSearchParams() を呼び出すと、最も近い Suspense 境界までのツリーがクライアントサイドでレンダリングされます。

これにより、ページの一部を静的にレンダリングしながら、searchParams を使用する動的な部分をクライアントサイドでレンダリングできます。

useSearchParams を使用するコンポーネントを Suspense 境界で囲むことで、クライアントサイドでレンダリングされる部分を減らすことができます。例:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // 静的レンダリング使用時、サーバーではログに記録されません
  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')

  // 静的レンダリング使用時、サーバーではログに記録されません
  console.log(search)

  return <>Search: {search}</>
}
import { Suspense } from 'react'
import SearchBar from './search-bar'

// Suspense 境界のフォールバックとして渡されたこのコンポーネントは、
// 初期 HTML で検索バーの代わりにレンダリングされます。
// React ハイドレーション中に値が利用可能になると、
// フォールバックは `<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'

// Suspense 境界のフォールバックとして渡されたこのコンポーネントは、
// 初期 HTML で検索バーの代わりにレンダリングされます。
// React ハイドレーション中に値が利用可能になると、
// フォールバックは `<SearchBar>` コンポーネントに置き換えられます。
function SearchBarFallback() {
  return <>placeholder</>
}

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

動的レンダリング

ルートが動的レンダリングされている場合、useSearchParams はクライアントコンポーネントの初期サーバーレンダリング時にサーバーで利用可能になります。

知っておくと便利: dynamic ルートセグメント設定オプションを force-dynamic に設定すると、動的レンダリングを強制できます。

例:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // 初期レンダリング時はサーバーでログに記録され、
  // 後続のナビゲーション時はクライアントで記録されます。
  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')

  // 初期レンダリング時はサーバーでログに記録され、
  // 後続のナビゲーション時はクライアントで記録されます。
  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>
    </>
  )
}

サーバーコンポーネント

ページ

ページ（サーバーコンポーネント）で検索パラメータにアクセスするには、searchParams プロップを使用します。

レイアウト

ページとは異なり、レイアウト（サーバーコンポーネント）は searchParams プロップを受け取りません。これは、共有レイアウトがナビゲーション中に再レンダリングされないため、ナビゲーション間で searchParams が古くなる可能性があるためです。詳細な説明を参照してください。

代わりに、ページの searchParams プロップを使用するか、クライアントコンポーネントで useSearchParams フックを使用してください。これにより、最新の searchParams でクライアント上で再レンダリングされます。

例

searchParams の更新

新しい searchParams を設定するには、useRouter または Link を使用できます。ナビゲーションが実行されると、現在の page.js は更新された searchParams プロップを受け取ります。

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

  // 現在の searchParams と提供されたキー/値のペアをマージして、
  // 新しい searchParams 文字列を取得します
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>並び替え</p>

      {/* useRouter を使用 */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        昇順
      </button>

      {/* <Link> を使用 */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        降順
      </Link>
    </>
  )
}
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // 現在の searchParams と提供されたキー/値のペアをマージして、
  // 新しい searchParams 文字列を取得します
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>並び替え</p>

      {/* useRouter を使用 */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        昇順
      </button>

      {/* <Link> を使用 */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        降順
      </Link>
    </>
  )
}

バージョン履歴

バージョン変更内容
v13.0.0useSearchParams が導入されました。

useRouter

useRouter フックのAPIリファレンス

useSelectedLayoutSegment

useSelectedLayoutSegment フックの API リファレンス