문서
App Router 사용하기
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>;
}
app/page.js
import Link from "next/link";
 
export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>;
}

Props

다음은 Link 컴포넌트에 사용 가능한 props의 요약입니다:

Prop예시타입필수 여부
hrefhref="/dashboard"String 또는 Object예
replacereplace={false}Boolean-
scrollscroll={false}Boolean-
prefetchprefetch={false}Boolean 또는 null-

알아두면 좋은 점: className 또는 target="_blank"와 같은 <a> 태그 속성들은 <Link>에 props로 추가될 수 있으며 기본 <a> 요소로 전달됩니다.

href (필수)

네비게이트할 경로 또는 URL입니다.

<Link href="/dashboard">대시보드</Link>

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

// /about?name=test로 네비게이트
<Link
  href={{
    pathname: "/about",
    query: { name: "test" },
  }}
>
  소개
</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>
  );
}
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}>
      대시보드
    </Link>
  );
}
app/page.js
import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      대시보드
    </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}>
      대시보드
    </Link>
  );
}
app/page.js
import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      대시보드
    </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> 태그를 감싸는 사용자 정의 컴포넌트인 경우, Link에 passHref를 추가해야 합니다. 이는 styled-components와 같은 라이브러리를 사용하는 경우 필요합니다. 이 없이는 <a> 태그가 href 속성을 갖지 않게 되어, 사이트의 접근성을 해치고 SEO에 영향을 줄 수 있습니다. ESLint를 사용하는 경우, passHref의 올바른 사용을 보장하는 내장 규칙 next/link-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의 JSX pragma 기능(@jsx jsx)을 사용하는 경우, <a> 태그를 직접 사용하더라도 passHref를 사용해야 합니다.
  • 컴포넌트는 네비게이션을 올바르게 트리거하기 위해 onClick 속성을 지원해야 합니다.

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

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

import Link from "next/link";
 
// `onClick`, `href`, 그리고 `ref` 속성들은 DOM 요소로 전달되어야
// 올바르게 처리됩니다
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      여기를 클릭하세요
    </a>
  );
});
 
function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  );
}
 
export default Home;

push 대신 URL 대체하기

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

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

페이지 상단으로의 스크롤 비활성화하기

Link의 기본 동작은 페이지 상단으로 스크롤하는 것입니다. 해시가 정의되어 있을 때는 일반 <a> 태그처럼 특정 id로 스크롤합니다. 상단 또는 해시로의 스크롤을 방지하려면 Link에 scroll={false}를 추가할 수 있습니다:

<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}>
      대시보드
    </Link>
  );
}

버전 기록

버전변경사항
v13.0.0더 이상 자식 <a> 태그가 필요하지 않습니다. 코드베이스를 자동으로 업데이트하기 위한 코드모드가 제공됩니다.
v10.0.0동적 라우트를 가리키는 href props가 자동으로 해결되며 더 이상 as prop이 필요하지 않습니다.
v8.0.0프리페칭 성능이 개선되었습니다.
v1.0.0next/link 도입.
<Image><Script>