<Link>

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

基本的な使い方

pages/index.tsx

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

リファレンス

以下の props を <Link> コンポーネントに渡すことができます

Prop	例	型	必須
`href`	`href="/dashboard"`	文字列またはオブジェクト	はい
`replace`	`replace={false}`	ブール	-
`scroll`	`scroll={false}`	ブール	-
`prefetch`	`prefetch={false}`	ブール	-
`legacyBehavior`	`legacyBehavior={true}`	ブール	-
`passHref`	`passHref={true}`	ブール	-
`shallow`	`shallow={false}`	ブール	-
`locale`	`locale="fr"`	文字列またはブール	-

知っておくと良いこと: className や target="_blank" などの <a> タグの属性を props として <Link> に追加できます。それらは基礎となる <a> 要素に渡されます。

`href` (必須)

ナビゲート先のパスまたは URL。

pages/index.tsx

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 を追加する代わりに、現在の履歴状態を置き換えます。

pages/index.tsx

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 は最初のページ要素へのスクロールを試行しません。

pages/index.tsx

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

`prefetch`

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

以下の値を prefetch prop に渡すことができます

true (デフォルト): ルートとそのデータが完全にプリフェッチされます。
false: ビューポートに入ったときのプリフェッチは行われず、ホバー時に行われます。ホバー時のフェッチも完全に削除したい場合は、<a>タグを使用するか、ホバー時のプリフェッチも無効にできるApp Routerを段階的に採用することを検討してください。

pages/index.tsx

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

`legacyBehavior`

<a>要素は、<Link>の子として必須ではなくなりました。レガシーな動作を使用する場合はlegacyBehaviorプロパティを追加し、アップグレードする場合は<a>を削除してください。コードを自動的にアップグレードするためのcodemodが利用可能です。

知っておくと良いこと: legacyBehaviorがtrueに設定されていない場合、anchorタグのプロパティ（className、onClickなど）は、next/linkにも渡すことができます。

`passHref`

Linkがその子にhrefプロパティを強制的に送信するようにします。デフォルトはfalseです。詳細については、関数型コンポーネントを渡すの例を参照してください。

`scroll`

ナビゲーション後、ページの先頭までスクロールします。デフォルトはtrueです。

pages/index.tsx

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

`shallow`

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

pages/index.tsx

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

`locale`

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

pages/index.tsx

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>
    </>
  )
}

例

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

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

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

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

pages/blog/index.tsx

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>
  )
}

子要素が`<a>`タグをラップするカスタムコンポーネントの場合

Linkの子が<a>タグをラップするカスタムコンポーネントの場合、passHrefをLinkに追加する必要があります。これは、styled-componentsのようなライブラリを使用している場合に必要です。これがないと、<a>タグにhref属性が設定されず、サイトのアクセシビリティが損なわれ、SEOに影響を与える可能性があります。ESLintを使用している場合は、passHrefを正しく使用するために、組み込みのルールnext/link-passhrefがあります。

components/nav-link.tsx

import Link from 'next/link'
import styled from 'styled-components'
 
// This creates a custom component that wraps an <a> tag
const RedLink = styled.a`
  color: red;
`
 
function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}
 
export default NavLink

emotionのJSXプラグマ機能（@jsx jsx）を使用している場合は、<a>タグを直接使用する場合でもpassHrefを使用する必要があります。
コンポーネントは、ナビゲーションを正しくトリガーするためにonClickプロパティをサポートする必要があります。

関数型コンポーネントのネスト

Linkの子が関数型コンポーネントの場合、passHrefとlegacyBehaviorを使用するのに加えて、コンポーネントをReact.forwardRefでラップする必要があります。

pages/index.tsx

import Link from 'next/link'
import React from 'react'
 
// Define the props type for MyButton
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}
 
// Use React.ForwardRefRenderFunction to properly type the forwarded ref
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
}
 
// Use React.forwardRef to wrap the component
const ForwardedMyButton = React.forwardRef(MyButton)
 
export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

URLオブジェクトの渡し方

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

pages/index.ts

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モジュールのドキュメントで定義されているすべてのプロパティを使用できます。

pushの代わりにURLを置換する

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

pages/index.js

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

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

ミドルウェアでのリンクのプリフェッチ

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

たとえば、認証済みビューとビジタービューを持つ /dashboard ルートを提供したい場合は、ミドルウェアに以下を追加してユーザーを正しいページにリダイレクトできます。

middleware.ts

import { NextResponse } from 'next/server'
 
export function middleware(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))
    }
  }
}

middleware.js

import { NextResponse } from 'next/server'
 
export function middleware(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

'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 href={path}>
      Dashboard
    </Link>
  )
}

知っておくと良いこと: 動的ルートを使用している場合は、as プロパティと href プロパティを調整する必要があります。たとえば、ミドルウェアを介して異なる表示をしたい /dashboard/authed/[user] のような動的ルートがある場合は、<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link> のように記述します。

バージョン履歴

バージョン	変更点
`v13.0.0`	子要素の `<a>` タグが不要になりました。コードベースを自動的に更新する codemod が提供されています。
`v10.0.0`	動的ルートを指す `href` プロパティは自動的に解決されるようになり、`as` プロパティは不要になりました。
`v8.0.0`	プリフェッチのパフォーマンスが向上しました。
`v1.0.0`	`next/link` が導入されました。