logoNext.js 日本語
ドキュメントブログ学習
はじめに/API リファレンス/コンポーネント/Link

Link

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

基本的な使用法:

import Link from 'next/link'

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

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

リファレンス

<Link>コンポーネントに渡せるプロパティ:

プロパティ例タイプ必須
hrefhref="/dashboard"文字列またはオブジェクトはい
replacereplace={false}ブール値-
scrollscroll={false}ブール値-
prefetchprefetch={false}ブール値-
legacyBehaviorlegacyBehavior={true}ブール値-
passHrefpassHref={true}ブール値-
shallowshallow={false}ブール値-
localelocale="fr"文字列またはブール値-
onNavigateonNavigate={(e) => {}}関数-

知っておくと良い: classNameやtarget="_blank"などの<a>タグ属性は、<Link>にプロパティとして追加でき、基盤となる<a>要素に渡されます。

href (必須)

移動先のパスまたはURL。

import Link from 'next/link'

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

// /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>
  )
}
import Link from 'next/link'

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

scroll

デフォルトはtrue。 Next.jsにおける<Link>のデフォルトのスクロール動作は、ブラウザが戻る/進むナビゲーションを処理する方法と同様にスクロール位置を維持します。Pageに移動する際、Pageがビューポート内に表示されている限り、スクロール位置は同じままです。ただし、Pageがビューポート内に表示されていない場合、Next.jsは最初のPage要素の先頭までスクロールします。

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

知っておくと良い: 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>
  )
}
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>
  )
}
import Link from 'next/link'

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

legacyBehavior

警告: legacyBehaviorプロパティはNext.js v16で削除されます。新しい<Link>動作を採用するには、<Link>の子として使用されている<a>タグをすべて削除してください。コードモッドが利用可能で、コードベースのアップグレードを自動化できます。

バージョン13以降、<Link>コンポーネントの子として<a>要素は不要になりました。互換性のために古い動作が必要な場合、legacyBehaviorプロパティを追加できます。

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

passHref

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

shallow

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

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/dashboard" shallow={false}>
      Dashboard
    </Link>
  )
}
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 (
    <>
      {/* デフォルト動作: ロケールが付加される */}
      <Link href="/dashboard">Dashboard (ロケール付き)</Link>

      {/* ロケール付加を無効化 */}
      <Link href="/dashboard" locale={false}>
        Dashboard (ロケールなし)
      </Link>

      {/* 異なるロケールを指定 */}
      <Link href="/dashboard" locale="fr">
        Dashboard (フランス語)
      </Link>
    </>
  )
}
import Link from 'next/link'

export default function Home() {
  return (
    <>
      {/* デフォルト動作: ロケールが付加される */}
      <Link href="/dashboard">Dashboard (ロケール付き)</Link>

      {/* ロケール付加を無効化 */}
      <Link href="/dashboard" locale={false}>
        Dashboard (ロケールなし)
      </Link>

      {/* 異なるロケールを指定 */}
      <Link href="/dashboard" locale="fr">
        Dashboard (フランス語)
      </Link>
    </>
  )
}

onNavigate

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

import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // SPAナビゲーション中のみ実行
        console.log('ナビゲーション中...')

        // 必要に応じてナビゲーションをキャンセル
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}
import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // SPAナビゲーション中のみ実行
        console.log('ナビゲーション中...')

        // 必要に応じてナビゲーションをキャンセル
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

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

  • 修飾キー（Ctrl/Cmd + クリック）を使用した場合、onClickは実行されますがonNavigateは実行されません（Next.jsが新しいタブのデフォルトナビゲーションを防ぐため）。
  • 外部URLはonNavigateをトリガーしません（クライアントサイドおよび同一オリジンナビゲーションのみ対象）。
  • download属性を持つリンクはonClickでは動作しますがonNavigateでは動作しません（ブラウザがリンクURLをダウンロードとして扱うため）。

例

以下の例は、さまざまなシナリオで<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>
  )
}
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>
  )
}

export default Posts

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

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

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
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 でコンポーネントをラップする必要があります:

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 Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}
import Link from 'next/link'
import React from 'react'

// `onClick`、`href`、`ref` は適切な処理のためにDOM要素に渡す必要がある
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
})

// デバッグ用にコンポーネントに表示名を追加
MyButton.displayName = 'MyButton'

export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}

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

上記の例では、次のリンクが作成されます:

Node.js URLモジュールドキュメントで定義されているすべてのプロパティを使用できます。

pushではなくURLを置換

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

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}
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}>
      トップへのスクロールを無効化
    </Link>
  )
}
import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      トップへのスクロールを無効化
    </Link>
  )
}

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

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

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

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

'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 認証フック

export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}
'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 認証フック

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]のようなダイナミックルートがある場合、次のように記述します: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>

ナビゲーションのブロック

フォームに未保存の変更がある場合など、特定の条件が満たされたときにナビゲーションをブロックするためにonNavigateプロップを使用できます。アプリ内の複数のコンポーネント（フォームが編集中の場合は任意のリンクからのナビゲーションを防止するなど）でナビゲーションをブロックする必要がある場合、Reactコンテキストはこのブロック状態を共有するクリーンな方法を提供します。まず、ナビゲーションブロック状態を追跡するコンテキストを作成します:

'use client'

import { createContext, useState, useContext } from 'react'

interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}

export const NavigationBlockerContext =
  createContext<NavigationBlockerContextType>({
    isBlocked: false,
    setIsBlocked: () => {},
  })

export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode
}) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}
'use client'

import { createContext, useState, useContext } from 'react'

export const NavigationBlockerContext = createContext({
  isBlocked: false,
  setIsBlocked: () => {},
})

export function NavigationBlockerProvider({ children }) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

コンテキストを使用するフォームコンポーネントを作成:

'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Save</button>
    </form>
  )
}
'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Save</button>
    </form>
  )
}

ナビゲーションをブロックするカスタムLinkコンポーネントを作成:

'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children: React.ReactNode
}

export function CustomLink({ children, ...props }: CustomLinkProps) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('未保存の変更があります。このまま移動しますか？')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}
'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

export function CustomLink({ children, ...props }) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('未保存の変更があります。このまま移動しますか？')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

ナビゲーションコンポーネントを作成:

'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">ホーム</Link>
      <Link href="/about">About</Link>
    </nav>
  )
}
'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">ホーム</Link>
      <Link href="/about">About</Link>
    </nav>
  )
}

最後に、ルートレイアウトでNavigationBlockerProviderでアプリをラップし、ページでコンポーネントを使用します:

import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}
import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

次に、ページでNavとFormコンポーネントを使用します:

import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>ダッシュボードへようこそ</h1>
        <Form />
      </main>
    </div>
  )
}
import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>ダッシュボードへようこそ</h1>
        <Form />
      </main>
    </div>
  )
}

フォームに未保存の変更がある状態でユーザーがCustomLinkを使用して移動しようとすると、移動前に確認を求められます。

バージョン履歴

バージョン変更点
v15.3.0onNavigate APIを追加
v13.0.0子要素の<a>タグが不要になりました。コードモッドが提供され、コードベースを自動的に更新できます。
v10.0.0ダイナミックルートを指すhrefプロップは自動的に解決され、asプロップが不要になりました。
v8.0.0プリフェッチのパフォーマンスが改善されました。
v1.0.0next/linkが導入されました。

Image (レガシー)

後方互換性を保ったImageコンポーネントによる画像最適化

Script

組み込みの `next/script` コンポーネントを使用して、Next.js アプリケーション内のサードパーティスクリプトを最適化します。