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

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

Prop例タイプ必須
hrefhref="/dashboard"ストリング または オブジェクトはい
replacereplace={false}ブール値-
scrollscroll={false}ブール値-
prefetchprefetch={false}ブール値 または null-

Good to know: className や target="_blank" などの <a> タグの属性は <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> デフォルトのスクロール挙動は、ブラウザが前後のナビゲーションで扱うように、スクロール位置を保持します。新しいページにナビゲートする際、ページがビューポートに表示される限りスクロール位置は変わりません。 However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element.

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

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 プロパティに渡すことができます：

  • 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> コンポーネントをどのように利用するかを示しています。

dynamic segmentsへのリンク​

dynamic segmentsにリンクする際、テンプレートリテラルと補間を利用してリンクのリストを生成できます。例えば、ブログ投稿のリストを生成するために:

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>

// Output
<a href="/dashboard#settings">Settings</a>

Good to know:

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

dynamic route segmentsへのリンク​

dynamic route segments において、テンプレートリテラルを使ってリンクのパスを作成することは便利です。

例えば、dynamic route 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> タグをラップするカスタムコンポーネントの場合​

Link の子が <a> タグをラップするカスタムコンポーネントである場合、passHref を Link に追加する必要があります。これは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 プロパティをサポートする必要があります。

関数コンポーネントのネスト​

Link の子が関数コンポーネントである場合、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 プロパティを使用できます：

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 を渡すことができます。

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

認証やユーザーを別のページにリダイレクトする特定の目的でMiddelwareを使用することが一般的です。<Link /> コンポーネントがMiddlewareを介して書き換えられたリンクを正しくプリフェッチするには、Next.jsに表示するURLとプリフェッチするURLの両方を伝える必要があります。これにより、正しいルートをプリフェッチするために、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 href={path}>
      Dashboard
    </Link>
  )
}

バージョン履歴​

バージョン変更点
v13.0.0子 <a> タグを必要としなくなりました。codemod が提供されており、コードベースを自動的に更新できます。
v10.0.0dynamic route を指す href プロパティが自動的に解決されるようになり、もはや as プロパティを必要としなくなりました。
v8.0.0プリフェッチのパフォーマンスが向上しました。
v1.0.0next/link が導入されました。