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

useRouter

useRouterフックは、Client Components内でプログラム的にルートを変更することを可能にします。

おすすめ: ナビゲーションには<Link>コンポーネントを使用してください。ただし、特定の要件があってuseRouterを使用する場合を除きます。

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 Server Componentペイロードをマージし、影響を受けないクライアント側のReact（例えば、useState）やブラウザの状態（例えば、スクロール位置）を失わないようにします
  • router.prefetch(href: string): クライアントサイドでの遷移を高速化するために、指定されたルートをプリフェッチします
  • router.back(): ブラウザの履歴スタックで前のルートに戻ります
  • router.forward(): ブラウザの履歴スタックで次のページに進みます

Good to know:

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

next/routerからの移行​

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

完全な移行ガイドを参照してください。

例​

Routerイベント​

usePathnameやuseSearchParamsのような他のクライアントコンポーネントフックを構成することでページの変更を監視できます。

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>はSuspense boundaryでラップされています。これはuseSearchParams()が静的レンダリング時に最も近いSuspense boundaryまでクライアントサイドレンダリングを引き起こすためです。詳しくはこちらをご覧ください。

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

デフォルトでは、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が導入されました。