문서
App Router 사용하기
API 참조
컴포넌트
Font

폰트

이 API 참조는 next/font/google와 next/font/local을 사용하는 방법을 이해하는 데 도움이 될 것입니다. 기능과 사용법에 대해서는 폰트 최적화 페이지를 참조하세요.

폰트 함수 인수

사용법은 Google 폰트와 로컬 폰트를 검토하세요.

키font/googlefont/local타입필수
src❌✔️문자열 또는 객체 배열예
weight✔️✔️문자열 또는 배열필수/선택
style✔️✔️문자열 또는 배열-
subsets✔️❌문자열 배열-
axes✔️❌문자열 배열-
display✔️✔️문자열-
preload✔️✔️불리언-
fallback✔️✔️문자열 배열-
adjustFontFallback✔️✔️불리언 또는 문자열-
variable✔️✔️문자열-
declarations❌✔️객체 배열-

src

폰트 로더 함수가 호출되는 디렉토리를 기준으로 한 폰트 파일의 경로를 문자열 또는 객체 배열(타입 Array<{path: string, weight?: string, style?: string}>)로 나타냅니다.

next/font/local에서 사용됨

  • 필수

예시:

  • src:'./fonts/my-font.woff2': my-font.woff2가 app 디렉토리 내의 fonts라는 디렉토리에 위치한 경우
  • src:[{path: './inter/Inter-Thin.ttf', weight: '100',},{path: './inter/Inter-Regular.ttf',weight: '400',},{path: './inter/Inter-Bold-Italic.ttf', weight: '700',style: 'italic',},]
  • 폰트 로더 함수가 app/page.tsx에서 src:'../styles/fonts/my-font.ttf'로 호출되는 경우, my-font.ttf는 프로젝트 루트의 styles/fonts에 위치합니다

weight

폰트 weight는 다음과 같은 옵션을 제공합니다:

  • 특정 폰트에 대해 사용 가능한 가중치의 값들 또는 가변 폰트인 경우 값의 범위를 나타내는 문자열
  • 폰트가 가변 Google 폰트가 아닌 경우 가중치 값의 배열. 이는 next/font/google에만 적용됩니다.

next/font/google와 next/font/local에서 사용됨

  • 사용하는 폰트가 가변이 아닌 경우 필수

예시:

  • weight: '400': 단일 가중치 값에 대한 문자열 - Inter 폰트의 경우, 가능한 값은 '100', '200', '300', '400', '500', '600', '700', '800', '900' 또는 'variable'입니다 ('variable'이 기본값)
  • weight: '100 900': 가변 폰트에 대한 100에서 900 사이의 범위를 나타내는 문자열
  • weight: ['100','400','900']: 가변이 아닌 폰트에 대한 3개의 가능한 값의 배열

style

폰트 style은 다음과 같은 옵션을 제공합니다:

  • 기본값이 'normal'인 문자열 값
  • 폰트가 가변 Google 폰트가 아닌 경우 스타일 값의 배열. 이는 next/font/google에만 적용됩니다.

next/font/google와 next/font/local에서 사용됨

  • 선택 사항

예시:

  • style: 'italic': 문자열 - next/font/google의 경우 normal 또는 italic일 수 있습니다
  • style: 'oblique': 문자열 - next/font/local의 경우 어떤 값이든 가능하지만 표준 폰트 스타일에서 가져올 것으로 예상됩니다
  • style: ['italic','normal']: next/font/google에 대한 2개의 값의 배열 - 값은 normal과 italic 중에서 선택됩니다

subsets

폰트 subsets는 프리로드하고 싶은 각 서브셋의 이름을 포함하는 문자열 배열로 정의됩니다. subsets를 통해 지정된 폰트는 preload 옵션이 true일 때(기본값) 헤드에 링크 프리로드 태그가 삽입됩니다.

next/font/google에서 사용됨

  • 선택 사항

예시:

  • subsets: ['latin']: 서브셋 latin을 포함하는 배열

모든 서브셋 목록은 사용하는 폰트의 Google Fonts 페이지에서 찾을 수 있습니다.

axes

일부 가변 폰트에는 포함할 수 있는 추가 axes가 있습니다. 기본적으로 파일 크기를 줄이기 위해 폰트 가중치만 포함됩니다. axes의 가능한 값은 특정 폰트에 따라 다릅니다.

next/font/google에서 사용됨

  • 선택 사항

예시:

  • axes: ['slnt']: Inter 가변 폰트에 대한 slnt 값을 포함하는 배열. Inter는 여기에 표시된 대로 추가 axes로 slnt를 가집니다. 폰트의 가능한 axes 값은 Google 가변 폰트 페이지의 필터를 사용하여 찾을 수 있으며, wght 이외의 축을 찾아보세요.

display

폰트 display는 'auto', 'block', 'swap', 'fallback' 또는 'optional'의 가능한 문자열 값을 가지며 기본값은 'swap'입니다.

next/font/google와 next/font/local에서 사용됨

  • 선택 사항

예시:

  • display: 'optional': optional 값이 할당된 문자열

preload

폰트를 미리 불러와야 하는지 여부를 지정하는 불리언 값입니다. 기본값은 true입니다.

next/font/google와 next/font/local에서 사용됨

  • 선택 사항

예시:

  • preload: false

fallback

폰트를 로드할 수 없는 경우 사용할 대체 폰트입니다. 기본값이 없는 대체 폰트의 문자열 배열입니다.

  • 선택 사항

next/font/google와 next/font/local에서 사용됨

예시:

  • fallback: ['system-ui', 'arial']: 대체 폰트를 system-ui 또는 arial로 설정하는 배열

adjustFontFallback

  • next/font/google의 경우: Cumulative Layout Shift를 줄이기 위해 자동 대체 폰트를 사용할지 여부를 설정하는 불리언 값입니다. 기본값은 true입니다.
  • next/font/local의 경우: Cumulative Layout Shift를 줄이기 위해 자동 대체 폰트를 사용할지 여부를 설정하는 문자열 또는 불리언 false 값입니다. 가능한 값은 'Arial', 'Times New Roman' 또는 false입니다. 기본값은 'Arial'입니다.

next/font/google와 next/font/local에서 사용됨

  • 선택 사항

예시:

  • adjustFontFallback: false: next/font/google의 경우
  • adjustFontFallback: 'Times New Roman': next/font/local의 경우

variable

스타일이 CSS 변수 방법으로 적용되는 경우 사용할 CSS 변수 이름을 정의하는 문자열 값입니다.

next/font/google와 next/font/local에서 사용됨

  • 선택 사항

예시:

  • variable: '--my-font': CSS 변수 --my-font가 선언됩니다

declarations

생성된 @font-face를 더 정의하는 font-face descriptor 키-값 쌍의 배열입니다.

next/font/local에서 사용됨

  • 선택 사항

예시:

  • declarations: [{ prop: 'ascent-override', value: '90%' }]

스타일 적용하기

폰트 스타일을 세 가지 방법으로 적용할 수 있습니다:

className

로드된 폰트에 대한 읽기 전용 CSS className을 HTML 요소에 전달하기 위해 반환합니다.

<p className={inter.className}>안녕하세요, Next.js!</p>

style

로드된 폰트에 대한 읽기 전용 CSS style 객체를 HTML 요소에 전달하기 위해 반환합니다. 여기에는 폰트 패밀리 이름과 대체 폰트에 접근하기 위한 style.fontFamily가 포함됩니다.

<p style={inter.style}>Hello World</p>

CSS 변수

외부 스타일 시트에서 스타일을 설정하고 추가 옵션을 지정하려면 CSS 변수 방법을 사용하세요.

폰트를 가져오는 것 외에도 CSS 변수가 정의된 CSS 파일을 가져오고 폰트 로더 객체의 변수 옵션을 다음과 같이 설정합니다:

app/page.tsx
import { Inter } from "next/font/google";
import styles from "../styles/component.module.css";
 
const inter = Inter({
  variable: "--font-inter",
});
app/page.js
import { Inter } from "next/font/google";
import styles from "../styles/component.module.css";
 
const inter = Inter({
  variable: "--font-inter",
});

폰트를 사용하려면 스타일을 적용하려는 텍스트의 부모 컨테이너의 className을 폰트 로더의 variable 값으로 설정하고 텍스트의 className을 외부 CSS 파일의 styles 속성으로 설정합니다.

app/page.tsx
<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>
app/page.js
<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>

component.module.css CSS 파일에서 text 선택자 클래스를 다음과 같이 정의합니다:

styles/component.module.css
.text {
  font-family: var(--font-inter);
  font-weight: 200;
  font-style: italic;
}

위의 예에서 Hello World 텍스트는 Inter 폰트와 생성된 폰트 대체를 사용하여 font-weight: 200과 font-style: italic로 스타일링됩니다.

폰트 정의 파일 사용하기

localFont 또는 Google 폰트 함수를 호출할 때마다 해당 폰트는 애플리케이션에서 하나의 인스턴스로 호스팅됩니다. 따라서 여러 곳에서 동일한 폰트를 사용해야 하는 경우, 한 곳에서 로드하고 필요한 곳에서 관련 폰트 객체를 가져와야 합니다. 이는 폰트 정의 파일을 사용하여 수행됩니다.

예를 들어, app 디렉토리의 루트에 있는 styles 폴더에 fonts.ts 파일을 만듭니다.

그런 다음 폰트 정의를 다음과 같이 지정합니다:

styles/fonts.ts
import { Inter, Lora, Source_Sans_3 } from "next/font/google";
import localFont from "next/font/local";
 
// 가변 폰트 정의
const inter = Inter();
const lora = Lora();
// 비가변 폰트의 2가지 가중치 정의
const sourceCodePro400 = Source_Sans_3({ weight: "400" });
const sourceCodePro700 = Source_Sans_3({ weight: "700" });
// styles 폴더에 저장된 GreatVibes-Regular.ttf의 사용자 정의 로컬 폰트 정의
const greatVibes = localFont({ src: "./GreatVibes-Regular.ttf" });
 
export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes };
styles/fonts.js
import { Inter, Lora, Source_Sans_3 } from "next/font/google";
import localFont from "next/font/local";
 
// 가변 폰트 정의
const inter = Inter();
const lora = Lora();
// 비가변 폰트의 2가지 가중치 정의
const sourceCodePro400 = Source_Sans_3({ weight: "400" });
const sourceCodePro700 = Source_Sans_3({ weight: "700" });
// styles 폴더에 저장된 GreatVibes-Regular.ttf의 사용자 정의 로컬 폰트 정의
const greatVibes = localFont({ src: "./GreatVibes-Regular.ttf" });
 
export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes };

이제 코드에서 다음과 같이 이러한 정의를 사용할 수 있습니다:

app/page.tsx
import { inter, lora, sourceCodePro700, greatVibes } from "../styles/fonts";
 
export default function Page() {
  return (
    <div>
      <p className={inter.className}>Inter 폰트를 사용한 Hello world</p>
      <p style={lora.style}>Lora 폰트를 사용한 Hello world</p>
      <p className={sourceCodePro700.className}>
        가중치 700의 Source_Sans_3 폰트를 사용한 Hello world
      </p>
      <p className={greatVibes.className}>Great Vibes 폰트의 내 제목</p>
    </div>
  );
}
app/page.js
import { inter, lora, sourceCodePro700, greatVibes } from "../styles/fonts";
 
export default function Page() {
  return (
    <div>
      <p className={inter.className}>Inter 폰트를 사용한 Hello world</p>
      <p style={lora.style}>Lora 폰트를 사용한 Hello world</p>
      <p className={sourceCodePro700.className}>
        가중치 700의 Source_Sans_3 폰트를 사용한 Hello world
      </p>
      <p className={greatVibes.className}>Great Vibes 폰트의 내 제목</p>
    </div>
  );
}

코드에서 폰트 정의에 더 쉽게 접근할 수 있도록 tsconfig.json 또는 jsconfig.json 파일에 경로 별칭을 다음과 같이 정의할 수 있습니다:

tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/fonts": ["./styles/fonts"]
    }
  }
}

이제 다음과 같이 모든 폰트 정의를 가져올 수 있습니다:

app/about/page.tsx
import { greatVibes, sourceCodePro400 } from "@/fonts";
app/about/page.js
import { greatVibes, sourceCodePro400 } from "@/fonts";

버전 변경

버전변경 사항
v13.2.0@next/font가 next/font로 이름 변경됨. 설치가 더 이상 필요 없음.
v13.0.0@next/font 추가됨.
API 참조<Form>