<link>

김동현·2026년 3월 17일
docsreact.js

react.js 공식문서 번역

목록 보기
79/92

<link>

소개

브라우저 내장 <link> 컴포넌트를 사용하면 스타일시트 같은 외부 리소스를 사용하거나 링크 메타데이터로 문서에 주석을 달 수 있어요.

<link rel="icon" href="favicon.ico" />

<link>는 CSS 파일, 폰트, 파비콘 등 외부 리소스를 HTML 문서에 연결하는 데 사용돼요. React에서는 어디서 렌더링하든 자동으로 <head>에 배치해주는 특별한 기능이 있어요!

목차

레퍼런스

스타일시트, 폰트, 아이콘 같은 외부 리소스를 링크하거나 링크 메타데이터로 문서에 주석을 달려면, 브라우저 내장 <link> 컴포넌트를 렌더링하세요. 어떤 컴포넌트에서든 <link>를 렌더링할 수 있고, React는 대부분의 경우 해당하는 DOM 요소를 문서 head에 배치할 거예요.

<link rel="icon" href="favicon.ico" />

아래에서 더 많은 예시를 확인해보세요.

Props

<link>는 모든 공통 요소 props를 지원해요.

다음 props는 rel="stylesheet"일 때 적용돼요:

  • precedence: 문자열이에요. 문서 <head> 내에서 다른 <link> DOM 노드와 비교해서 어디에 순위를 매길지 React에게 알려주며, 이는 어떤 스타일시트가 다른 것을 재정의할 수 있는지 결정해요. React는 먼저 발견한 precedence 값이 "낮고" 나중에 발견한 precedence 값이 "높다"고 추론할 거예요. 많은 스타일 시스템은 스타일 규칙이 원자적이기 때문에 단일 precedence 값을 사용해서도 잘 작동할 수 있어요. 동일한 precedence를 가진 스타일시트는 <link>든 인라인 <style> 태그든 preinit 함수를 사용해서 로드되었든 함께 그룹화돼요.
  • media: 문자열이에요. 스타일시트를 특정 미디어 쿼리로 제한해요.
  • title: 문자열이에요. 대체 스타일시트의 이름을 지정해요.

다음 props는 rel="stylesheet"일 때 적용되지만 React의 스타일시트 특별 처리를 비활성화해요:

  • disabled: boolean이에요. 스타일시트를 비활성화해요.
  • onError: 함수예요. 스타일시트가 로드에 실패했을 때 호출돼요.
  • onLoad: 함수예요. 스타일시트 로드가 완료되었을 때 호출돼요.

다음 props는 rel="preload" 또는 rel="modulepreload"일 때 적용돼요:

  • as: 문자열이에요. 리소스의 유형이에요. 가능한 값은 audio, document, embed, fetch, font, image, object, script, style, track, video, worker예요.
  • imageSrcSet: 문자열이에요. as="image"일 때만 적용돼요. 이미지의 소스 세트를 지정해요.
  • imageSizes: 문자열이에요. as="image"일 때만 적용돼요. 이미지의 크기를 지정해요.

다음 props는 rel="icon" 또는 rel="apple-touch-icon"일 때 적용돼요:

다음 props는 모든 경우에 적용돼요:

  • href: 문자열이에요. 링크된 리소스의 URL이에요.
  • crossOrigin: 문자열이에요. 사용할 CORS 정책이에요. 가능한 값은 anonymous와 use-credentials예요. as가 "fetch"로 설정되었을 때 필수예요.
  • referrerPolicy: 문자열이에요. 페칭할 때 보낼 Referrer 헤더예요. 가능한 값은 no-referrer-when-downgrade(기본값), no-referrer, origin, origin-when-cross-origin, unsafe-url이에요.
  • fetchPriority: 문자열이에요. 리소스를 페칭하는 상대적 우선순위를 제안해요. 가능한 값은 auto(기본값), high, low예요.
  • hrefLang: 문자열이에요. 링크된 리소스의 언어예요.
  • integrity: 문자열이에요. 진위를 확인하기 위한 리소스의 암호화 해시예요.
  • type: 문자열이에요. 링크된 리소스의 MIME 타입이에요.

React에서 사용이 권장되지 않는 Props:

  • blocking: 문자열이에요. "render"로 설정하면, 스타일시트가 로드될 때까지 브라우저가 페이지를 렌더링하지 않도록 지시해요. React는 Suspense를 사용해서 더 세밀한 제어를 제공해요.

특별한 렌더링 동작

React는 React 트리의 어디에서 렌더링되든 상관없이 <link> 컴포넌트에 해당하는 DOM 요소를 항상 문서의 <head> 안에 배치할 거예요. <head>는 DOM 내에서 <link>가 존재할 수 있는 유일하게 유효한 위치지만, 특정 페이지를 나타내는 컴포넌트가 <link> 컴포넌트 자체를 렌더링할 수 있다면 편리하고 구성 가능성을 유지할 수 있어요.

여기에는 몇 가지 예외가 있어요:

  • <link>에 rel="stylesheet" prop이 있으면, 이 특별한 동작을 얻으려면 precedence prop도 있어야 해요. 문서 내 스타일시트의 순서가 중요하기 때문에, React는 precedence prop을 사용해서 지정하는 다른 스타일시트와 비교해서 이 스타일시트를 어떻게 순서를 매길지 알아야 해요. precedence prop이 생략되면 특별한 동작이 없어요.
  • <link>에 itemProp prop이 있으면 특별한 동작이 없어요. 이 경우 문서에 적용되는 것이 아니라 페이지의 특정 부분에 대한 메타데이터를 나타내기 때문이에요.
  • <link>에 onLoad 또는 onError prop이 있으면 특별한 동작이 없어요. 이 경우 React 컴포넌트 내에서 링크된 리소스의 로딩을 수동으로 관리하고 있기 때문이에요.

스타일시트에 대한 특별한 동작

추가로, <link>가 스타일시트에 대한 것이라면(즉, props에 rel="stylesheet"가 있으면), React는 다음과 같은 방식으로 특별하게 처리해요:

  • <link>를 렌더링하는 컴포넌트는 스타일시트가 로딩되는 동안 suspend할 거예요.
  • 여러 컴포넌트가 동일한 스타일시트에 대한 링크를 렌더링하면, React는 중복을 제거하고 DOM에 단일 링크만 넣을 거예요. 두 링크가 동일한 href prop을 가지고 있으면 같은 것으로 간주돼요.

이 특별한 동작에는 두 가지 예외가 있어요:

  • 링크에 precedence prop이 없으면 특별한 동작이 없어요. 문서 내 스타일시트의 순서가 중요하기 때문에, React는 precedence prop을 사용해서 지정하는 다른 스타일시트와 비교해서 이 스타일시트를 어떻게 순서를 매길지 알아야 해요.
  • onLoad, onError, 또는 disabled props 중 하나라도 제공하면 특별한 동작이 없어요. 이러한 props는 컴포넌트 내에서 스타일시트의 로딩을 수동으로 관리하고 있다는 것을 나타내기 때문이에요.

이 특별한 처리에는 두 가지 주의사항이 있어요:

  • React는 링크가 렌더링된 후 props 변경을 무시할 거예요. (React는 개발 모드에서 이런 일이 발생하면 경고를 발생시킬 거예요.)
  • React는 링크를 렌더링한 컴포넌트가 언마운트된 후에도 DOM에 링크를 남길 수 있어요.

사용법

관련 리소스 링크하기

아이콘, canonical URL, pingback 같은 관련 리소스에 대한 링크로 문서에 주석을 달 수 있어요. React는 React 트리의 어디에서 렌더링되든 상관없이 이 메타데이터를 문서 <head> 안에 배치할 거예요.

// src/App.js
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function BlogPage() {
  return (
    <ShowRenderedHTML>
      <link rel="icon" href="favicon.ico" />
      <link rel="pingback" href="http://www.example.com/xmlrpc.php" />
      <h1>My Blog</h1>
      <p>...</p>
    </ShowRenderedHTML>
  );
}

위 예시에서 <link> 태그들이 BlogPage 컴포넌트 안에 있지만, React가 자동으로 HTML의 <head> 섹션에 배치해줘요!

스타일시트 링크하기

컴포넌트가 올바르게 표시되기 위해 특정 스타일시트에 의존하는 경우, 컴포넌트 내에서 해당 스타일시트에 대한 링크를 렌더링할 수 있어요. 컴포넌트는 스타일시트가 로딩되는 동안 suspend할 거예요. precedence prop을 제공해야 하는데, 이는 React에게 이 스타일시트를 다른 것과 비교해서 어디에 배치할지 알려줘요 — 더 높은 precedence를 가진 스타일시트는 더 낮은 것을 재정의할 수 있어요.

참고

스타일시트를 사용하고 싶을 때, preinit 함수를 호출하는 것이 유익할 수 있어요. 이 함수를 호출하면 <link> 컴포넌트를 렌더링하는 것만으로는 할 수 없는, 예를 들어 HTTP Early Hints 응답을 보내는 등의 방법으로 브라우저가 스타일시트를 더 일찍 페칭하기 시작할 수 있게 해줘요.

// src/App.js
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function SiteMapPage() {
  return (
    <ShowRenderedHTML>
      <link rel="stylesheet" href="sitemap.css" precedence="medium" />
      <p>...</p>
    </ShowRenderedHTML>
  );
}

스타일시트 우선순위 제어하기

스타일시트는 서로 충돌할 수 있고, 충돌하면 브라우저는 문서에서 나중에 오는 것을 선택해요. React는 precedence prop으로 스타일시트의 순서를 제어할 수 있게 해줘요. 이 예시에서 세 개의 컴포넌트가 스타일시트를 렌더링하고, 동일한 precedence를 가진 것들이 <head> 안에서 함께 그룹화돼요.

// src/App.js
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function HomePage() {
  return (
    <ShowRenderedHTML>
      <FirstComponent />
      <SecondComponent />
      <ThirdComponent/>
      ...
    </ShowRenderedHTML>
  );
}

function FirstComponent() {
  return <link rel="stylesheet" href="first.css" precedence="first" />;
}

function SecondComponent() {
  return <link rel="stylesheet" href="second.css" precedence="second" />;
}

function ThirdComponent() {
  return <link rel="stylesheet" href="third.css" precedence="first" />;
}

위 예시에서 FirstComponent와 ThirdComponent는 둘 다 precedence="first"를 가지고 있어서 <head> 안에서 함께 그룹화될 거예요. SecondComponent는 precedence="second"를 가지고 있어서 나중에 배치되고, 따라서 "first" precedence를 가진 스타일을 재정의할 수 있어요.

precedence 값 자체는 임의적이고 이름 짓는 것은 여러분에게 달려 있어요. React는 먼저 발견한 precedence 값이 "낮고" 나중에 발견한 precedence 값이 "높다"고 추론할 거예요.

중복 제거된 스타일시트 렌더링

여러 컴포넌트에서 동일한 스타일시트를 렌더링하면, React는 문서 head에 단일 <link>만 배치할 거예요.

// src/App.js
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function HomePage() {
  return (
    <ShowRenderedHTML>
      <Component />
      <Component />
      ...
    </ShowRenderedHTML>
  );
}

function Component() {
  return <link rel="stylesheet" href="styles.css" precedence="medium" />;
}

위 예시에서 Component가 두 번 렌더링되어도, <link>는 HTML head에 한 번만 나타나요. 이렇게 중복을 자동으로 제거해주는 것이 React의 특별한 기능이에요!

문서 내 특정 항목에 링크로 주석 달기

itemProp prop과 함께 <link> 컴포넌트를 사용해서 문서 내 특정 항목에 관련 리소스에 대한 링크로 주석을 달 수 있어요. 이 경우 React는 이러한 주석을 문서 <head> 안에 배치하지 않고 다른 React 컴포넌트처럼 배치할 거예요.

<section itemScope>
  <h3>Annotating specific items</h3>
  <link itemProp="author" href="http://example.com/" />
  <p>...</p>
</section>

위 코드에서 itemProp이 있으면, 이 링크는 문서 전체가 아니라 해당 <section> 내의 특정 항목에 대한 메타데이터를 나타내므로, <head>로 이동하지 않고 그 자리에 그대로 있어요.

사이트맵

모든 문서 페이지 개요

profile
김동현
프론트에_가까운_풀스택_개발자
이전 포스트

<textarea>

다음 포스트

<meta>

0개의 댓글