Link

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

基本的な使用法：

TypeScript
JavaScript

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

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

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

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

リファレンス

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

Prop	Example	Type	Required
`href`	`href="/dashboard"`	String or Object	Yes
`replace`	`replace={false}`	Boolean	-
`scroll`	`scroll={false}`	Boolean	-
`prefetch`	`prefetch={false}`	Boolean or null	-
`onNavigate`	`onNavigate={(e) => {}}`	Function	-

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

`href`（必須）

ナビゲートするパスまたは URL。

TypeScript
JavaScript

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

app/page.js
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 を追加しません。

TypeScript
JavaScript

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

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

app/page.js
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 は最初のページ要素にスクロールしようとしません。

Good to know: Next.js はスクロール動作を管理する前に scroll: false を確認します。スクロールが有効な場合、ナビゲーションの関連する DOM ノードを特定し、各トップレベル要素を検査します。すべてのスクロール不可能な要素とレンダリングされた HTML を持たない要素はバイパスされます。これには、固定位置の要素や getBoundingClientRect で計算された非表示の要素が含まれます。Next.js は、ビューポートに表示されるスクロール可能な要素を特定するまで、兄弟要素を通過し続けます。

TypeScript
JavaScript

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

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

app/page.js
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：ビューポートに入るときもホバー時もプリフェッチは行われません。

TypeScript
JavaScript

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

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

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

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

`onNavigate`

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

TypeScript
JavaScript

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

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

        // ナビゲーションをオプションで防ぐ
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

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

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

        // ナビゲーションをオプションで防ぐ
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

Good to know: onClick と onNavigate は似ているように見えますが、異なる目的を持っています。onClick はすべてのクリックイベントに対して実行されますが、onNavigate はクライアントサイドのナビゲーション中にのみ実行されます。いくつかの重要な違い：

修飾キー（Ctrl/Cmd + クリック）を使用する場合、onClick は実行されますが、onNavigate は実行されません。Next.js は新しいタブのデフォルトのナビゲーションを防ぐためです。

外部 URL は onNavigate をトリガーしません。これはクライアントサイドおよび同一オリジンのナビゲーションにのみ適用されるためです。

download 属性を持つリンクは、ブラウザがリンクされた URL をダウンロードとして扱うため、onClick では動作しますが、onNavigate では動作しません。

例

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

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

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

TypeScript
JavaScript

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

app/blog/post-list.js
import Link from 'next/link'

export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

アクティブなリンクの確認

usePathname() を使用して、リンクがアクティブかどうかを判断できます。たとえば、アクティブなリンクにクラスを追加するには、現在の pathname がリンクの href と一致するかどうかを確認します：

TypeScript
JavaScript

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

app/ui/nav-links.js
'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 prop にハッシュリンクを渡すことができます。これは、<Link> が <a> 要素にレンダリングされるため可能です。

<Link href="/dashboard#settings">Settings</Link>

// 出力
<a href="/dashboard#settings">Settings</a>

Good to know:

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

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

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

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

TypeScript
JavaScript

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

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

TypeScript
JavaScript

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

components/nav-link.js
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 でラップする必要があります：

TypeScript
JavaScript

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

app/page.js
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 Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}

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

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

TypeScript
JavaScript

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

export default function Page() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

app/page.js
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 を渡します。

JavaScript
TypeScript

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

export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </Link>
  )
}

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

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

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

たとえば、認証済みと訪問者のビューを持つ /dashboard ルートを提供したい場合、ミドルウェアでユーザーを正しいページにリダイレクトするために次のコードを追加できます：

TypeScript
JavaScript

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 /> コンポーネントで次のコードを使用することをお勧めします：

TypeScript
JavaScript

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

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

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

TypeScript
JavaScript

app/contexts/navigation-blocker.tsx
'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)
}

app/contexts/navigation-blocker.js
'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)
}

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

TypeScript
JavaScript

app/components/form.tsx
'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>
  )
}

app/components/form.js
'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>
  )
}

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

TypeScript
JavaScript

app/components/custom-link.tsx
'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('You have unsaved changes. Leave anyway?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

app/components/custom-link.js
'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('You have unsaved changes. Leave anyway?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

ナビゲーションコンポーネントを作成します：

TypeScript
JavaScript

app/components/nav.tsx
'use client'

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

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

app/components/nav.js
'use client'

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

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

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

TypeScript
JavaScript

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

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

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

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

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

TypeScript
JavaScript

app/page.tsx
import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Welcome to the Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

app/page.js
import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Welcome to the Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

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

バージョン履歴

Version	Changes
`v15.3.0`	`onNavigate` API を追加
`v13.0.0`	子 `<a>` タグが不要になりました。コードモッドが提供されており、コードベースを自動的に更新できます。
`v10.0.0`	動的ルートを指す `href` props は自動的に解決され、`as` prop を必要としなくなりました。
`v8.0.0`	プリフェッチのパフォーマンスが向上しました。
`v1.0.0`	`next/link` が導入されました。

リファレンス​

href（必須）​

replace​

scroll​

prefetch​

onNavigate​

例​

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

アクティブなリンクの確認​

id へのスクロール​

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

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

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

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

ページの上部へのスクロールを無効にする​

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

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

バージョン履歴​