Link

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

基本的な使用方法：

pages/index.tsx

TypeScript

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

リファレンス

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

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

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

`href`（必須）

移動先のパスまたは URL。

pages/index.tsx

TypeScript

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

`replace`

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

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  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 はビューポート内に表示されるスクロール可能な要素を特定するまでスキャン検索を続けます。

pages/index.tsx

TypeScript

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

`prefetch`

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

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

true（デフォルト）：完全なルートおよびそのデータがプリフェッチされます。
false：ビューポート進入時のプリフェッチングは発生しませんが、ホバー時には発生します。ホバー時のフェッチングを完全に削除したい場合は、<a> タグを使用するか、段階的に採用することを検討してください。これにより App Router がホバー時のプリフェッチングを無効にすることもできます。

pages/index.tsx

TypeScript

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

`shallow`

現在のページのパスを更新しますが、getStaticProps、getServerSideProps、getInitialPropsを再実行しません。デフォルトは false です。

pages/index.tsx

TypeScript

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

`locale`

アクティブなロケールが自動的に前置されます。locale により異なるロケールを提供できます。false の場合、href にはロケールを含める必要があります。デフォルト動作は無効になります。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <>
      {/* デフォルト動作：ロケールが前置される */}
      <Link href="/dashboard">Dashboard (ロケール付き)</Link>
 
      {/* ロケール前置を無効化 */}
      <Link href="/dashboard" locale={false}>
        Dashboard (ロケール無し)
      </Link>
 
      {/* 異なるロケールを指定 */}
      <Link href="/dashboard" locale="fr">
        Dashboard (フランス語)
      </Link>
    </>
  )
}

`as`

ブラウザの URL バーに表示されるパスのオプション修飾子。Next.js 9.5.3 より前は、これはダイナミックルートのために使用されていました。使い方については以前のドキュメントを確認してください。

このパスが href で提供されるパスと異なる場合、以前のドキュメントに示されているように、以前の href/as 動作が使用されます。

`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> コンポーネントを使用する方法を示しています。

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

ダイナミックルートセグメントへのリンク時、テンプレートリテラルを使用してリンクのパスを作成すると便利です。

たとえば、ダイナミックルート pages/blog/[slug].js へのリンクのリストを生成できます

pages/blog/index.tsx

TypeScript

import Link from 'next/link'
 
function Posts({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

`id` にスクロール

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

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

URL オブジェクトを渡す

Link は URL オブジェクトも受け取ることができ、URL 文字列を作成するために自動的にフォーマットされます：

pages/index.ts

TypeScript

import Link from 'next/link'
 
function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          About us
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blog Post
        </Link>
      </li>
    </ul>
  )
}
 
export default Home

上記の例は以下へのリンクを示しています：

事前に定義されたルート：/about?name=test
ダイナミックルート：/blog/my-post

Node.js URL モジュールドキュメントで定義されているすべてのプロパティを使用できます。

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

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

pages/index.js

TypeScript

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

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

Link のデフォルト動作はページの先頭にスクロールすることです。ハッシュが定義されている場合、通常の <a> タグと同様に特定の ID にスクロールします。ページ先頭/ハッシュへのスクロールを防ぐには、Link に scroll={false} を追加できます：

pages/index.tsx

TypeScript

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

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 /> コンポーネントで以下のコードを使用します：

pages/index.tsx

TypeScript

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

補足：ダイナミックルートを使用している場合は、as および href プロパティを適応させる必要があります。たとえば、Proxy 経由で別の方法で表示したい /dashboard/authed/[user] のようなダイナミックルートがある場合は、次のように記述します：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>。

バージョン履歴

バージョン	変更内容
`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` が導入されました。