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

useRouter

useRouter フックを使用すると、Client Components内でプログラム的にルートを変更できます。

推奨事項： ナビゲーションには、特定の要件がない限り、<Link> コンポーネントを使用してください。

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

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

useRouter()​

  • router.push(href: string, { scroll: boolean }): 指定されたルートへのクライアントサイドのナビゲーションを実行します。新しいエントリをブラウザの履歴スタックに追加します。
  • router.replace(href: string, { scroll: boolean }): 指定されたルートへのクライアントサイドのナビゲーションを実行しますが、ブラウザの履歴スタックに新しいエントリを追加しません。
  • router.refresh(): 現在のルートをリフレッシュします。サーバーへの新しいリクエストを行い、データリクエストを再取得し、Server Componentsを再レンダリングします。クライアントは、影響を受けないクライアントサイドのReact（例：useState）やブラウザの状態（例：スクロール位置）を失うことなく、更新されたReact Server Componentのペイロードをマージします。
  • router.prefetch(href: string): 指定されたルートをプリフェッチし、クライアントサイドの遷移を高速化します。
  • router.back(): ブラウザの履歴スタックで前のルートに戻ります。
  • router.forward(): ブラウザの履歴スタックで次のページに進みます。

Good to know:

  • router.push または router.replace に信頼できない、またはサニタイズされていないURLを送信してはいけません。これにより、サイトがクロスサイトスクリプティング（XSS）の脆弱性にさらされる可能性があります。例えば、javascript: URLを router.push または router.replace に送信すると、ページのコンテキストで実行されます。
  • <Link> コンポーネントは、ビューポートに表示されると自動的にルートをプリフェッチします。
  • refresh() は、フェッチリクエストがキャッシュされている場合、同じ結果を再現する可能性があります。他の動的API（例：cookies や headers）もレスポンスを変更する可能性があります。

next/router からの移行​

  • useRouter フックは、App Routerを使用する際には next/router ではなく next/navigation からインポートする必要があります
  • pathname 文字列は削除され、usePathname()に置き換えられました
  • query オブジェクトは削除され、useSearchParams()に置き換えられました
  • router.events は置き換えられました。以下を参照してください。

完全な移行ガイドを表示。

例​

Router events​

usePathname や useSearchParams などの他のClient Componentフックを組み合わせることで、ページの変更を監視できます。

app/components/navigation-events.js
'use client'

import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

export function NavigationEvents() {
  const pathname = usePathname()
  const searchParams = useSearchParams()

  useEffect(() => {
    const url = `${pathname}?${searchParams}`
    console.log(url)
    // 現在のURLを使用できます
    // ...
  }, [pathname, searchParams])

  return '...'
}

これをレイアウトにインポートできます。

app/layout.js
import { Suspense } from 'react'
import { NavigationEvents } from './components/navigation-events'

export default function Layout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}

        <Suspense fallback={null}>
          <NavigationEvents />
        </Suspense>
      </body>
    </html>
  )
}

Good to know: <NavigationEvents> は、useSearchParams()が静的レンダリング中に最も近い Suspense 境界までクライアントサイドのレンダリングを引き起こすため、Suspense 境界でラップされています。詳細はこちら。

スクロールトップの無効化​

デフォルトでは、Next.jsは新しいルートに移動するときにページのトップにスクロールします。この動作を無効にするには、router.push() または router.replace() に scroll: false を渡します。

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

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}

バージョン履歴​

バージョン変更点
v13.0.0next/navigation から useRouter が導入されました。