Link コンポーネント

<Link> は HTML の <a> 要素を拡張した React コンポーネントで、プリフェッチングとルート間のクライアント側ナビゲーションを提供します。これは Next.js でルート間を移動する主な方法です。

基本的な使用方法：

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

リファレンス

以下のプロパティを <Link> コンポーネントに渡すことができます：

プロパティ	例	型	必須
`href`	`href="/dashboard"`	文字列またはオブジェクト	はい
`replace`	`replace={false}`	ブール値	-
`scroll`	`scroll={false}`	ブール値	-
`prefetch`	`prefetch={false}`	ブール値または null	-
`onNavigate`	`onNavigate={(e) => {}}`	関数	-

補足：className や target="_blank" などの <a> タグの属性を <Link> にプロパティとして追加すると、基になる <a> 要素に渡されます。

`href`（必須）

移動先のパスまたは URL。

app/page.tsx

TypeScript

import Link from 'next/link'
 
// /about?name=test に移動
export default function Page() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}

`replace`

デフォルトは false です。 true の場合、next/link は新しい URL をブラウザの履歴スタックに追加する代わりに、現在の履歴状態を置き換えます。

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

デフォルトは true です。 Next.js における <Link> のデフォルトのスクロール動作はスクロール位置を維持することで、ブラウザが戻る・進む操作を処理する方法に似ています。新しいページに移動する場合、ページがビューポート内に表示されている限り、スクロール位置は同じままです。ただし、ページがビューポート内に表示されていない場合、Next.js は最初のページ要素の先頭にスクロールします。

scroll = {false} の場合、Next.js は最初のページ要素にスクロールしようとしません。

補足：Next.js はスクロール動作を管理する前に scroll: false をチェックします。スクロールが有効な場合は、ナビゲーション用の関連する DOM ノードを識別し、各トップレベル要素を検査します。スクロール不可能な要素と描画される HTML がない要素は除外されます。これには固定位置またはスティッキー位置の要素や getBoundingClientRect で計算されるような非表示の要素が含まれます。その後、Next.js はビューポート内に表示されるスクロール可能な要素を特定するまでスキャン検索を続けます。

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

`prefetch`

プリフェッチングは <Link /> コンポーネントがユーザーのビューポートに入ると（最初またはスクロール経由で）発生します。Next.js はリンク先のルート（href で示される）およびそのデータをバックグラウンドでプリフェッチして読み込み、クライアント側ナビゲーションのパフォーマンスを向上させます。プリフェッチされたデータがユーザーが <Link /> にホバーした時点で期限切れになっている場合、Next.js は再度プリフェッチを試みます。プリフェッチングは本番環境でのみ有効です。

prefetch プロパティに以下の値を渡すことができます：

"auto" または null（デフォルト）：プリフェッチ動作はルートが静的か動的かに依存します。静的ルートの場合、完全なルートがプリフェッチされます（すべてのデータを含む）。動的ルートの場合、loading.jsバウンダリを持つ最も近いセグメントまでの部分的なルートがプリフェッチされます。
true：静的および動的ルートの両方に対して完全なルートがプリフェッチされます。
false：ビューポート進入時とホバー時の両方で、プリフェッチングは発生しません。

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

`onNavigate`

クライアント側ナビゲーション中に呼び出されるイベントハンドラ。ハンドラは preventDefault() メソッドを含むイベントオブジェクトを受け取り、必要に応じてナビゲーションをキャンセルできます。

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // SPA ナビゲーション中のみ実行される
        console.log('ナビゲーション中...')
 
        // 必要に応じてナビゲーションを防止
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

補足：onClick と onNavigate は似ているように見えますが、異なる目的に使われます。onClick はすべてのクリックイベントに対して実行されますが、onNavigate はクライアント側ナビゲーション中のみ実行されます。いくつかの主な違いがあります：

修飾キー（Ctrl/Cmd + クリック）を使用する場合、onClick は実行されますが、onNavigate は実行されません。Next.js は新規タブでのデフォルトナビゲーションを防止するためです。

外部 URL は onNavigate をトリガーしません。これはクライアント側および同一オリジンのナビゲーションのみだからです。

download 属性を持つリンクは onClick では機能しますが、onNavigate では機能しません。ブラウザはリンク先の URL をダウンロードとして扱うためです。

例

以下の例では、異なるシナリオで <Link> コンポーネントを使用する方法を示しています。

ダイナミックルートセグメントへのリンク

ダイナミックセグメントへリンクする場合、テンプレートリテラルと補間を使用してリンクのリストを生成できます。たとえば、ブログ投稿のリストを生成するには：

app/blog/post-list.tsx

TypeScript

import Link from 'next/link'
 
interface Post {
  id: number
  title: string
  slug: string
}
 
export default function PostList({ posts }: { posts: Post[] }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

アクティブなリンクをチェック

usePathname()を使用してリンクがアクティブかどうかを判定できます。たとえば、アクティブなリンクにクラスを追加するには、現在の pathname がリンクの href と一致するかをチェックできます：

app/ui/nav-links.tsx

TypeScript

'use client'
 
import { usePathname } from 'next/navigation'
import Link from 'next/link'
 
export function Links() {
  const pathname = usePathname()
 
  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>
 
      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}

`id` にスクロール

ナビゲーション時に特定の id にスクロールしたい場合、URL に # ハッシュリンクを追加するか、単に href プロパティにハッシュリンクを渡すことができます。これは <Link> が <a> 要素にレンダリングされるため可能です。

<Link href="/dashboard#settings">Settings</Link>
 
// 出力
<a href="/dashboard#settings">Settings</a>

補足：

ナビゲーション時にビューポート内にページが表示されていない場合、Next.js はそのページにスクロールします。

履歴スタックにプッシュする代わりに URL を置き換え

Link コンポーネントのデフォルト動作は新しい URL を history スタックにプッシュすることです。次の例のように、replace プロパティを使用して新しいエントリが追加されるのを防ぐことができます：

app/page.js

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

ページ先頭へのスクロールを無効化

Next.js における <Link> のデフォルトのスクロール動作はスクロール位置を維持することで、ブラウザが戻る・進む操作を処理する方法に似ています。新しいページに移動する場合、ページがビューポート内に表示されている限り、スクロール位置は同じままです。

ただし、ページがビューポート内に表示されていない場合、Next.js は最初のページ要素の先頭にスクロールします。この動作を無効にしたい場合、<Link> コンポーネントに scroll={false} を渡すか、router.push() または router.replace() に scroll: false を渡すことができます。

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      ページ先頭へのスクロールを無効化
    </Link>
  )
}

router.push() または router.replace() を使用する場合：

// useRouter
import { useRouter } from 'next/navigation'
 
const router = useRouter()
 
router.push('/dashboard', { scroll: false })

Proxy を使用したリンクのプリフェッチ

Proxyを認証やその他の目的で使用して、ユーザーを別のページにリライトするのは一般的です。<Link /> コンポーネントが Proxy 経由でリライトされたリンクを適切にプリフェッチするため、Next.js に表示する URL とプリフェッチする URL の両方を伝える必要があります。これは Proxy への不要なフェッチを避けるために必要です。これにより、プリフェッチするべき正しいルートが認識されます。

たとえば、認証されたビューと訪問者ビューを持つ /dashboard ルートを提供したい場合、Proxy に以下を追加してユーザーを正しいページにリダイレクトできます：

proxy.ts

TypeScript

import { NextResponse } from 'next/server'
 
export function proxy(request: Request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}

この場合、<Link /> コンポーネントで以下のコードを使用します：

app/page.tsx

TypeScript

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 認証フック
 
export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

ナビゲーションをブロック

onNavigate プロパティを使用して、フォームに保存されていない変更があるなど、特定の条件が満たされたときにナビゲーションをブロックできます。アプリ内の複数のコンポーネント全体でナビゲーションをブロックする必要がある場合（フォームが編集されている間は任意のリンクからのナビゲーションを防止するなど）、React Context はこのブロック状態を共有する明確な方法を提供します。まず、ナビゲーションブロック状態を追跡するコンテキストを作成します：

app/contexts/navigation-blocker.tsx

TypeScript

'use client'
 
import { createContext, useState, useContext } from 'react'
 
interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}
 
export const NavigationBlockerContext =
  createContext<NavigationBlockerContextType>({
    isBlocked: false,
    setIsBlocked: () => {},
  })
 
export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode
}) {
  const [isBlocked, setIsBlocked] = useState(false)
 
  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}
 
export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

コンテキストを使用するフォームコンポーネントを作成します：

app/components/form.tsx

TypeScript

'use client'
 
import { useNavigationBlocker } from '../contexts/navigation-blocker'
 
export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()
 
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Save</button>
    </form>
  )
}

ナビゲーションをブロックするカスタム Link コンポーネントを作成します：

app/components/custom-link.tsx

TypeScript

'use client'
 
import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'
 
interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children: React.ReactNode
}
 
export function CustomLink({ children, ...props }: CustomLinkProps) {
  const { isBlocked } = useNavigationBlocker()
 
  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('保存されていない変更があります。とにかく離れますか？')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

ナビゲーションコンポーネントを作成します：

app/components/nav.tsx

TypeScript

'use client'
 
import { CustomLink as Link } from './custom-link'
 
export default function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
    </nav>
  )
}

最後に、アプリをルートレイアウトの NavigationBlockerProvider でラップし、ページでコンポーネントを使用します：

app/layout.tsx

TypeScript

import { NavigationBlockerProvider } from './contexts/navigation-blocker'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

その後、ページで Nav および Form コンポーネントを使用します：

app/page.tsx

TypeScript

import Nav from './components/nav'
import Form from './components/form'
 
export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>ダッシュボードへようこそ</h1>
        <Form />
      </main>
    </div>
  )
}

ユーザーが CustomLink を使用してナビゲーションを試みている間、フォームに保存されていない変更がある場合、ナビゲーションを進める前に確認するよう求められます。

バージョン履歴

バージョン	変更内容
`v15.4.0`	デフォルトの `prefetch` 動作のエイリアスとして `auto` を追加しました。
`v15.3.0`	`onNavigate` API を追加しました。
`v13.0.0`	子の `<a>` タグが不要になりました。コードベースを自動的に更新するためのコードモッドが提供されています。
`v10.0.0`	ダイナミックルートを指す `href` プロパティが自動的に解決されるようになり、`as` プロパティが不要になりました。
`v8.0.0`	プリフェッチ性能を改善しました。
`v1.0.0`	`next/link` が導入されました。