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> コンポーネントには以下のpropsを渡すことができます：

Prop	例	型	必須
`href`	`href="/dashboard"`	String または Object	はい
`replace`	`replace={false}`	Boolean	-
`scroll`	`scroll={false}`	Boolean	-
`prefetch`	`prefetch={false}`	Boolean または null	-

補足: className や target="_blank" などの <a> タグの属性は、propsとして <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> のデフォルトのスクロール動作は、スクロール位置を維持することであり、ブラウザの戻る/進むナビゲーションと同様の動作です。新しいPageに移動する場合、そのPageがビューポート内に表示されている限り、スクロール位置は同じままです。ただし、Pageがビューポート内に表示されていない場合、Next.jsは最初のPage要素の先頭にスクロールします。

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

補足: Next.jsはスクロール動作を管理する前に scroll: false をチェックします。スクロールが有効な場合、関連するDOMノードを特定し、各トップレベル要素を検査します。スクロール不可能な要素や、レンダリングされたHTMLを持たない要素（stickyまたはfixed位置の要素、viewport内に表示されていない要素など）はスキップされます。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 プロップには以下の値を渡すことができます：

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

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

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

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はナビゲーション時にPageがビューポートに表示されていない場合、そのPageにスクロールします。

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

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

例えば、動的ルート 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>
  )
}

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

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

関数コンポーネントをネストする

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

app/page.tsx

TypeScript

import Link from 'next/link'
import React from 'react'
 
// MyButtonのpropsタイプを定義
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>
  )
}

pushではなく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> のデフォルトのスクロール動作は、スクロール位置を維持することであり、ブラウザの戻る/進むナビゲーションと同様の動作です。新しいPageに移動する場合、そのPageがビューポート内に表示されている限り、スクロール位置は同じままです。

ただし、Pageがビューポート内に表示されていない場合、Next.jsは最初のPage要素の先頭にスクロールします。この動作を無効にしたい場合は、<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を認証やその他の目的で使用し、ユーザーを別のページにリダイレクトすることは一般的です。Middlewareを介してリダイレクトされるリンクを <Link /> コンポーネントが適切にプリフェッチするには、Next.jsに表示するURLとプリフェッチするURLの両方を伝える必要があります。これは、プリフェッチする正しいルートを知るためにミドルウェアへの不要なフェッチを避けるために必要です。

例えば、認証済みユーザーとビジター用のビューを持つ /dashboard ルートを提供したい場合、Middlewareに以下を追加して、ユーザーを正しいページにリダイレクトできます：

middleware.ts

TypeScript

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

この場合、<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>
  )
}

バージョン履歴

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