メインコンテンツまでスキップ

useSearchParams

useSearchParamsは現在のURLのクエリ文字列を読み取ることができるClient Componentフックです。

useSearchParamsは、URLSearchParamsインターフェイスの読み取り専用バージョンを返します。

app/dashboard/search-bar.tsx
'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}</>
}

Parameters​

const searchParams = useSearchParams()

useSearchParamsはパラメータを一切受け取りません。

Returns​

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

  • 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

  • URLSearchParamsの他の読み取り専用メソッドについてもっと学びましょう；getAll()、keys()、values()、entries()、forEach()、toString()が含まれます。

Good to know:

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

Behavior​

Static Rendering​

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

これにより、ルートの一部が静的にレンダリングされる一方で、useSearchParamsを使用する動的部分がクライアント側でレンダリングされます。

useSearchParamsを使用するClient Componentを<Suspense/>境界でラップすることをお勧めします。これにより、その上のClient Componentが静的にレンダリングされ、初期HTMLの一部として送信されます。 例。

例えば：

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/page.tsx
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>
    </>
  )
}

Dynamic Rendering​

ルートが動的にレンダリングされている場合、useSearchParamsはClient Componentの初期サーバーレンダリング中にサーバー上で利用可能です。

例えば：

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/page.tsx
import SearchBar from './search-bar'

export const dynamic = 'force-dynamic'

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

Good to know: dynamicルートセグメントのコンフィグオプションをforce-dynamicに設定することで、動的レンダリングを強制することができます。

Server Components​

Pages​

Pages（Server Components）で検索パラメータにアクセスするためには、searchParamsプロップを使用してください。

Layouts​

Pagesとは異なり、Layouts（Server Components）はsearchParamsプロップを受け取りません。これは、共有レイアウトがナビゲーション中に再レンダリングされないため、ナビゲーション間でsearchParamsが古くなる可能性を避けるためです。 詳細な説明をご覧ください。

代わりに、PageのsearchParamsプロップまたはClient Componentで再レンダリングされるuseSearchParamsフックをクライアント上で使用してください。これにより、クライアント側の最新のsearchParamsで更新されます。

Examples​

searchParamsの更新​

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

app/example-client-component.tsx
'use client'

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.toString())
      params.set(name, value)

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

  return (
    <>
      <p>Sort By</p>

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

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

バージョン履歴​

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