🎉 공식문서 번역에 참여해주세요.  🐙  Github 바로가기  🐙
Docs
App Router
API Reference
Components
Link

<Link>

<Link>는 HTML <a> 요소를 확장하여 사전 로딩 및 라우트 간의 클라이언트 사이드 내비게이션을 제공합니다. Next.js에서 라우트 간의 이동을 위한 주요 방법입니다.

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

속성

다음은 Link 컴포넌트에 사용할 수 있는 속성의 요약입니다:

속성예제타입필수
hrefhref="/dashboard"문자열 또는 객체예
replacereplace={false}불리언-
scrollscroll={false}불리언-
prefetchprefetch={false}불리언 또는 null-

참고: className 또는 target="_blank"와 같은 <a> 태그 속성은 <Link>에 속성으로 추가할 수 있으며, 이는 기본 <a> 요소에 전달됩니다.

href (필수)

이동할 경로 또는 URL입니다.

<Link href="/dashboard">Dashboard</Link>

href는 객체를 받을 수도 있습니다. 예를 들어:

// /about?name=test로 이동
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  About
</Link>

replace

기본값은 false입니다. true일 때, next/link는 브라우저의 히스토리 (opens in a new tab) 스택에 새 URL을 추가하는 대신 현재 히스토리 상태를 대체합니다.

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입니다. <Link>의 기본 동작은 새 라우트로 이동할 때 페이지 맨 위로 스크롤하거나, 뒤로 및 앞으로 이동할 때 스크롤 위치를 유지하는 것입니다. false일 때, next/link는 탐색 후 페이지 맨 위로 스크롤하지 않습니다.

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

참고:

  • Next.js는 탐색 시 페이지가 뷰포트에 보이지 않으면 페이지로 스크롤합니다.

prefetch

사전 로딩은 <Link /> 컴포넌트가 사용자의 뷰포트에 들어올 때(처음이거나 스크롤을 통해) 발생합니다. Next.js는 백그라운드에서 링크된 라우트(href로 표시됨)와 데이터를 사전 로딩하여 클라이언트 측 내비게이션 성능을 향상시킵니다. 사전 로딩은 프로덕션에서만 활성화됩니다.

  • 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>
  )
}
app/page.js
import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

예제

동적 라우트로 링크 연결

동적 라우트를 위해 링크의 경로를 생성할 때 템플릿 리터럴을 사용하는 것이 편리할 수 있습니다.

예를 들어, app/blog/[slug]/page.js의 동적 라우트로 링크 목록을 생성할 수 있습니다:

app/blog/page.js
import Link from 'next/link'
 
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 (opens in a new tab)와 같은 라이브러리를 사용하는 경우에 필요합니다. 그렇지 않으면 <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
  • emotion (opens in a new tab)의 JSX 프래그마 기능(@jsx jsx)을 사용하는 경우, <a> 태그를 직접 사용하더라도 passHref를 사용해야 합니다.
  • 컴포넌트는 내비게이션을 올바르게 트리거하기 위해 onClick 속성을 지원해야 합니다.

자식이 함수형 컴포넌트인 경우

Link의 자식이 함수형 컴포넌트인 경우, passHref 및 legacyBehavior를 사용하는 것 외에도 컴포넌트를 React.forwardRef (opens in a new tab)로 감싸야 합니다:

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>
  )
})
 
function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}
 
export default Home

URL을 푸시 대신 교체

Link 컴포넌트의 기본 동작은 history 스택에 새 URL을 push하는 것입니다. 다음 예제와 같이 replace 속성을 사용하여 새 항목을 추가하지 않도록 할 수 있습니다:

<Link href="/about" replace>
  About us
</Link>

페이지 맨 위로 스크롤 비활성화

Link의 기본 동작은 페이지 맨 위로 스크롤하는 것입니다. 해시가 정의된 경우 일반 <a> 태그처럼 특정 ID로 스크롤합니다. 맨 위로 스크롤하거나 해시로 스크롤하는 것을 방지하려면 scroll={false}를 Link에 추가할 수 있습니다:

<Link href="/#hashid" scroll={false}>
  Disables scrolling to the top
</Link>

미들웨어

미들웨어를 사용하여 인증 또는 다른 목적으로 사용자를 다른 페이지로 리디렉션하는 경우가 많습니다. <Link /> 컴포넌트가 미들웨어를 통한 리디렉션 링크를 올바르게 미리 가져오려면, Next.js에 표시할 URL과 미리 가져올 URL을 모두 알려야 합니다. 이는 올바른 경로를 미리 가져오기 위해 미들웨어에 불필요한 요청을 방지하기 위해 필요합니다.

예를 들어, 인증된 사용자와 방문자 보기를 모두 제공하는 /dashboard 경로가 있다고 가정합니다. 다음과 같이 미들웨어에 사용자를 올바른 페이지로 리디렉션하는 코드를 추가할 수 있습니다:

middleware.js
export function middleware(req) {
  const nextUrl = req.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (req.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', req.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', req.url))
    }
  }
}

이 경우, <Link /> 컴포넌트에서 다음 코드를 사용해야 합니다:

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> 태그가 필요하지 않습니다. 자동으로 코드베이스를 업데이트하는 코드 수정 도구가 제공됩니다.
v10.0.0동적 라우트를 가리키는 href 속성이 자동으로 해결되며 더 이상 as 속성이 필요하지 않습니다.
v8.0.0미리 가져오기 성능이 향상되었습니다.
v1.0.0next/link 도입.
ImageScript