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

補足：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>
  )
}

`scroll`

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

scroll = {false} の場合、Next.jsは最初のページ要素へのスクロールを試みません。

app/page.tsx

TypeScript

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

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

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

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

プリフェッチは、<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>
  )
}

`legacyBehavior`

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

補足: legacyBehavior が true に設定されていない場合、className、onClick などのすべての anchor タグのプロパティを next/link に渡すこともできます。

`passHref`

Link に href プロパティを子に強制的に送信させます。デフォルトは false です。詳細は関数コンポーネントの入れ子の例を参照してください。

`scroll`

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

pages/index.tsx

TypeScript

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

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 (with locale)</Link>
 
      {/* ロケールの先頭付加を無効化 */}
      <Link href="/dashboard" locale={false}>
        Dashboard (without locale)
      </Link>
 
      {/* 異なるロケールを指定 */}
      <Link href="/dashboard" locale="fr">
        Dashboard (French)
      </Link>
    </>
  )
}

例

以下の例は、異なるシナリオでの <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>

補足:

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

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

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

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

app/blog/page.tsx

TypeScript

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

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

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

components/nav-link.tsx

TypeScript

import Link from 'next/link'
import styled from 'styled-components'
 
// これは<a>タグをラップするカスタムコンポーネントを作成します
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でラップする必要があります：

app/page.tsx

TypeScript

import Link from 'next/link'
import React from 'react'
 
// MyButtonのプロップスの型を定義
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}
 
// 転送されたrefを適切に型付けするために、React.ForwardRefRenderFunctionを使用
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
}
 
// コンポーネントをReact.forwardRefでラップ
const ForwardedMyButton = React.forwardRef(MyButton)
 
export default function Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

URLを置き換える代わりにプッシュ

Linkコンポーネントのデフォルトの動作は、新しいURLをhistoryスタックにpushすることです。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 })

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

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

例えば、認証済みとゲスト用のビューを持つ/dashboardルートを提供する場合、以下のようにMiddlewareでユーザーを正しいページにリダイレクトできます:

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

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 href={path}>
      ダッシュボード
    </Link>
  )
}

app/page.js

'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}>
      ダッシュボード
    </Link>
  )
}

バージョン履歴

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