メインコンテンツまでスキップ

Link

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

基本的な使用法：

app/page.tsx
import Link from 'next/link'

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

参照​

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

PropExampleTypeRequired
hrefhref="/dashboard"String or ObjectYes
replacereplace={false}Boolean-
scrollscroll={false}Boolean-
prefetchprefetch={false}Boolean or null-

Good to know: <a> タグの属性（たとえば、className や target="_blank"）は、<Link> にpropsとして追加でき、それらは基礎となる <a> 要素に渡されます。

href (必須)​

移動するパスまたはURL。

app/page.tsx
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
import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

scroll​

デフォルトは true。 Next.jsでの<Link>のデフォルトのスクロール動作は スクロール位置を保持すること です。これは、ブラウザが前後に移動する際の処理方法に似ています。新しいPageに移動する際、Pageはビューポート内に表示されている限り、スクロール位置はそのままになります。しかし、Pageがビューポートに表示されていない場合、Next.jsは最初のPage要素の先頭にスクロールします。

scroll = {false} の場合、Next.jsは最初のPage要素にスクロールしようとしません。

Good to know: Next.jsはscroll: falseかどうかをチェックしてから、スクロール動作を管理します。スクロールが有効になっている場合、ナビゲーションに関連するDOMノードを特定し、各トップレベル要素を検査します。スクロールできない要素や、レンダリングされたHTMLがない要素（この中には、固定された要素や getBoundingClientRect で計算された非表示要素が含まれます）を全てバイパスし、表示されているスクロール可能な要素が特定されるまで兄弟要素を確認し続けます。

app/page.tsx
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 propに渡せる値は次の通りです。

  • null (デフォルト): ルートが静的か動的かによってプリフェッチの動作が異なります。静的ルートでは、完全なルート（すべてのデータを含む）がプリフェッチされます。動的ルートでは loading.js 境界までの最も近いセグメントまで部分的にプリフェッチされます。
  • true: 静的ルートと動的ルートの両方で完全なルートがプリフェッチされます。
  • false: ビューポートに入ったときとホバー時のいずれの場合もプリフェッチは行われません。
app/page.tsx
import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

使用例​

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

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

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

app/blog/post-list.tsx
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
'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>

Good to know:

  • ナビゲーション時にPageがビューポート内に表示されていない場合、Next.jsはPageにスクロールします。

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

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

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

app/blog/page.tsx
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> タグをラップするカスタムコンポーネントを子に持つ場合​

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

components/nav-link.tsx
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 プロパティをサポートするべきです。

Functionalコンポーネントのネスト​

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

app/page.tsx
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>
  )
}

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

Link コンポーネントのデフォルトの動作は history スタックに新しいURLを push することです。以下の例のように、新しいエントリを追加するのを防ぐには、replace propを使用できます。

app/page.js
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.js
import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </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に指示する必要があります。これにより、正しいルートをプリフェッチするためにMiddlewareへの不必要なフェッチを避けることができます。

たとえば、認証ビューと訪問者ビューを持つ /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
'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 props が自動的に解決され、もはや as prop を必要としなくなりました。
v8.0.0プリフェッチのパフォーマンスが向上しました。
v1.0.0next/link が導入されました。