コンテンツにスキップ
APIリファレンスコンポーネントLink

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

リファレンス

<Link>コンポーネントに以下のプロパティを渡すことができます

プロパティ例型必須
hrefhref="/dashboard"StringまたはObjectはい
replacereplace={false}Boolean-
scrollscroll={false}Boolean-
prefetchprefetch={false}Booleanまたはnull-
onNavigateonNavigate={(e) => {}}Function-

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

href (必須)

移動先のパスまたはURL。

app/page.tsx
import Link from 'next/link'
 
// Navigate to /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>のデフォルトのスクロール動作は、ブラウザが戻る/進むナビゲーションを処理するのと同様に、スクロール位置を維持することです。新しいページに移動すると、そのページがビューポートに表示されている限り、スクロール位置は同じままです。しかし、ページがビューポートに表示されていない場合、Next.jsは最初のページ要素のトップにスクロールします。

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

補足: Next.jsはスクロール動作を管理する前にscroll: falseが設定されているかを確認します。スクロールが有効な場合、ナビゲーションに関連するDOMノードを特定し、各トップレベル要素を調べます。スクロール不可能な要素やHTMLがレンダリングされていない要素はスキップされます。これには、固定または絶対配置の要素、およびgetBoundingClientRectで計算された非表示要素が含まれます。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>
  )
}

onNavigate

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

app/page.tsx
import Link from 'next/link'
 
export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Only executes during SPA navigation
        console.log('Navigating...')
 
        // Optionally prevent navigation
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

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

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

例

以下の例は、さまざまなシナリオで<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>
 
// Output
<a href="/dashboard#settings">Settings</a>

補足:

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

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

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

例えば、動的ルート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>タグをラップするカスタムコンポーネントである場合、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'
 
// This creates a custom component that wraps an <a> tag
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'
 
// Define the props type for MyButton
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}
 
// Use React.ForwardRefRenderFunction to properly type the forwarded ref
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
}
 
// Use React.forwardRef to wrap the component
const ForwardedMyButton = React.forwardRef(MyButton)
 
export default function Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

プッシュではなくURLを置換

Linkコンポーネントのデフォルトの動作は、新しいURLをhistoryスタックに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.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ルートを提供したい場合、ユーザーを正しいページにリダイレクトするためにミドルウェアに以下を追加できます。

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

この場合、<Link />コンポーネントで以下のコードを使用することになります。

app/page.tsx
'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Your auth hook
 
export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

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

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

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

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

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

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

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

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

バージョン履歴

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