Link

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

基本的な使い方

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。

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

`replace`

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

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はその後、ビューポート内で表示されているスクロール可能な要素を特定するまで、兄弟要素を検索し続けます。

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を段階的に採用することを検討してください。これにより、ホバー時のプリフェッチを無効にすることもできます。

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

`shallow`

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

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

`locale`

アクティブなロケールが自動的に先頭に付けられます。locale を使用すると、異なるロケールを指定できます。false の場合、href にロケールを含める必要があります。これは、デフォルトの動作が無効になっているためです。

import Link from 'next/link'
 
export default function Home() {
  return (
    <>
      {/* Default behavior: locale is prepended */}
      <Link href="/dashboard">Dashboard (with locale)</Link>
 
      {/* Disable locale prepending */}
      <Link href="/dashboard" locale={false}>
        Dashboard (without locale)
      </Link>
 
      {/* Specify a different locale */}
      <Link href="/dashboard" locale="fr">
        Dashboard (French)
      </Link>
    </>
  )
}

`as`

ブラウザのURLバーに表示されるパスのオプションのデコレーター。Next.js 9.5.3より前は、動的ルートに使用されていました。その仕組みについては、以前のドキュメントを確認してください。

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

`onNavigate`

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

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Only executes during SPA navigation
        console.log('Navigating...')
 
        // Optionally prevent navigation
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

知っておくと便利: onClick と onNavigate は似ているように見えますが、異なる目的を持っています。onClick はすべてのクリックイベントで実行されますが、onNavigate はクライアントサイドナビゲーション中にのみ実行されます。いくつかの重要な違い:

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

onNavigate はクライアントサイドおよび同一オリジンのナビゲーションのみに適用されるため、外部URLは onNavigate をトリガーしません。

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

例

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

動的ルートセグメントへのリンク

動的ルートセグメントの場合、テンプレートリテラルを使用してリンクのパスを作成すると便利です。

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

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>
 
// Output
<a href="/dashboard#settings">Settings</a>

URLオブジェクトの渡り

Link はURLオブジェクトを受け取ることもでき、自動的にURL文字列を作成するようにフォーマットします。

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コンポーネントのデフォルトの動作は、historyスタックに新しいURLをpushすることです。次の例のように、新しいエントリを追加しないように replace プロップスを使用できます。

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

ページトップへのスクロールを無効にする

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

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </Link>
  )
}

Proxyでのリンクのプリフェッチ

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

たとえば、認証済みビューと訪問者ビューを持つ /dashboard ルートを提供したい場合、Proxyに次のように追加できます。これにより、ユーザーは正しいページにリダイレクトされます。

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 />コンポーネントで次のコードを使用することになります

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

知っておくと便利: 動的ルートを使用している場合、asとhrefプロップスを適応させる必要があります。たとえば、`/dashboard/authed/[user]` のような動的ルートがあり、Proxy経由で異なる表示をしたい場合、次のように記述します: <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>` タグは不要になりました。codemod を使用して、コードベースを自動的に更新できます。
`v10.0.0`	動的ルートを指す `href` プロップスは自動的に解決され、`as` プロップスは不要になりました。
`v8.0.0`	プリフェッチパフォーマンスが向上しました。
`v1.0.0`	`next/link` が導入されました。