Lang x Lang

︙

useSearchParams

useSearchParamsは、現在の URL のquery stringを読み取ることができるClient Componentの hook です。

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

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}</>
}
app/dashboard/search-bar.js
'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は、URL の query string を読み取るためのユーティリティ Method を含むURLSearchParams インターフェースの読み取り専用の version を返します。

  • URLSearchParams.get() ：検索パラメータに関連付けられた最初の value を返します。例えば：
URLsearchParams.get("a")
/dashboard?a=1'1'
/dashboard?a=''
/dashboard?b=3null
/dashboard?a=1&a=2'1' - getAll() を使用してすべての値を取得します
  • URLSearchParams.has() ：指定されたパラメータが存在するかどうかを示す boolean value を返します。例えば：
URLsearchParams.has("a")
/dashboard?a=1true
/dashboard?b=3false

Good to know:

  • useSearchParams はClient Componentの hook であり、部分的なレンダリング中の stale 値を防ぐために、Server Componentsではサポートされていません。
  • アプリケーションが/pagesディレクトリを含んでいる場合、useSearchParamsはReadonlyURLSearchParams | nullを返します。nullの value は、getServerSidePropsを使用しないページの事前レンダリング中に検索 params がわからないため、移行中の互換性のためです。

静的レンダリング

route が静的にレンダリングされている場合、useSearchParamsを呼び出すと、最も近いSuspense boundaryまでの Client Component ツリーが Client サイドでレンダリングされます。

これにより、useSearchParamsを使用する dynamic 部分が Client サイドでレンダリングされる一方で、route の一部を静的にレンダリングすることが可能になります。

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

For example:

app/dashboard/search-bar.tsx
'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // This will not be logged on the server when using static rendering
  console.log(search)

  return <>Search: {search}</>
}
app/dashboard/search-bar.js
'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // This will not be logged on the server when using static rendering
  console.log(search)

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

// This component passed as a fallback to the Suspense boundary
// will be rendered in place of the search bar in the initial HTML.
// When the value is available during React hydration the fallback
// will be replaced with the `<SearchBar>` component.
function SearchBarFallback() {
  return <>placeholder</>
}

export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}
app/dashboard/page.js
import { Suspense } from 'react'
import SearchBar from './search-bar'

// This component passed as a fallback to the Suspense boundary
// will be rendered in place of the search bar in the initial HTML.
// When the value is available during React hydration the fallback
// will be replaced with the `<SearchBar>` component.
function SearchBarFallback() {
  return <>placeholder</>
}

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

Behavior

Dynamic Rendering

もし route がdynamically renderedされている場合、useSearchParams は初期の server render 等で Client Component の server 上で利用可能になります。

For example:

app/dashboard/search-bar.tsx
'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // This will be logged on the server during the initial render
  // and on the client on subsequent navigations.
  console.log(search)

  return <>Search: {search}</>
}
app/dashboard/search-bar.js
'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // This will be logged on the server during the initial render
  // and on the client on subsequent navigations.
  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>
    </>
  )
}
app/dashboard/page.js
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 route セグメントの config オプションをforce-dynamicに設定することで、 dynamic レンダリングを強制することができます。

Server Components

Pages

Pages(Server Components)で params 検索にアクセスするには、searchParams プロップを使用します。

Layouts

Pages とは異なり、layouts(Server Components)は、searchParamsプロップを受け取りません。これは、共有される layout がナビゲーション中に再 rendering されないため、ナビゲーション間で stale なsearchParamsが発生する可能性があるからです。詳細な説明をご覧ください。

代わりに、Page searchParams prop またはuseSearchParams hook を Client Component で使用してください。これは、最新のsearchParamsで client 上で再レンダリングされます。

Examples

searchParamsの更新

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

app/example-client-component.tsx
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // Get a new searchParams string by merging the current
  // searchParams with a provided key/value pair
  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>

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

      {/* using <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}
app/example-client-component.js
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // Get a new searchParams string by merging the current
  // searchParams with a provided key/value pair
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

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

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

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

Version History

VersionChanges
v13.0.0useSearchParams が導入されました。

当社サイトでは、Cookie を使用しています。各規約をご確認の上ご利用ください:
Cookie Policy, Privacy Policy および Terms of Use