Unverified Commit e91de8e0 authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs: `next/font` updates (#46159)


Update `next/font` docs pages for version 13.2, rename `@next/font` to `next/font` and remove installation instructions. 

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] [e2e](https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) tests added
- [x] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have a helpful link attached, see [`contributing.md`](https://github.com/vercel/next.js/blob/canary/contributing.md)

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm build && pnpm lint`
- [ ] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
Co-authored-by: 's avatarJJ Kasper <22380829+ijjk@users.noreply.github.com>
parent 9df7df13
--- ---
description: Optimizing loading web fonts with the built-in `@next/font` loaders. description: Optimizing loading web fonts with the built-in `next/font` loaders.
--- ---
# @next/font # next/font
<details> <details>
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | ----------------------- | | --------- | --------------------------------------------------------------------- |
| `v13.0.0` | `@next/font` was added. | | `v13.2.0` | `@next/font` renamed to `next/font`. Installation no longer required. |
| `v13.0.0` | `next/font` was added. |
</details> </details>
This API reference will help you understand how to use `@next/font/google` and `@next/font/local`. For features and usage, please see the [Optimizing Fonts](/docs/basic-features/font-optimization.md) page. This API reference will help you understand how to use `next/font/google` and `next/font/local`. For features and usage, please see the [Optimizing Fonts](/docs/basic-features/font-optimization.md) page.
### Font function arguments ### Font function arguments
...@@ -37,7 +38,7 @@ For usage, review [Google Fonts](/docs/basic-features/font-optimization.md#googl ...@@ -37,7 +38,7 @@ For usage, review [Google Fonts](/docs/basic-features/font-optimization.md#googl
The path of the font file as a string or an array of objects (with type `Array<{path: string, weight?: string, style?: string}>`) relative to the directory where the font loader function is called. The path of the font file as a string or an array of objects (with type `Array<{path: string, weight?: string, style?: string}>`) relative to the directory where the font loader function is called.
Used in `@next/font/local` Used in `next/font/local`
- Required - Required
...@@ -52,9 +53,9 @@ Examples: ...@@ -52,9 +53,9 @@ Examples:
The font [`weight`](https://fonts.google.com/knowledge/glossary/weight) with the following possibilities: The font [`weight`](https://fonts.google.com/knowledge/glossary/weight) with the following possibilities:
- A string with possible values of the weights available for the specific font or a range of values if it's a [variable](https://fonts.google.com/variablefonts) font - A string with possible values of the weights available for the specific font or a range of values if it's a [variable](https://fonts.google.com/variablefonts) font
- An array of weight values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `@next/font/google` only. - An array of weight values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `next/font/google` only.
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
- Required if the font being used is **not** [variable](https://fonts.google.com/variablefonts) - Required if the font being used is **not** [variable](https://fonts.google.com/variablefonts)
...@@ -69,23 +70,23 @@ Examples: ...@@ -69,23 +70,23 @@ Examples:
The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with the following possibilities: The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with the following possibilities:
- A string [value](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style#values) with default value of `'normal'` - A string [value](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style#values) with default value of `'normal'`
- An array of style values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `@next/font/google` only. - An array of style values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `next/font/google` only.
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
- Optional - Optional
Examples: Examples:
- `style: 'italic'`: A string - it can be `normal` or `italic` for `@next/font/google` - `style: 'italic'`: A string - it can be `normal` or `italic` for `next/font/google`
- `style: 'oblique'`: A string - it can take any value for `@next/font/local` but is expected to come from [standard font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) - `style: 'oblique'`: A string - it can take any value for `next/font/local` but is expected to come from [standard font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)
- `style: ['italic','normal']`: An array of 2 values for `@next/font/google` - the values are from `normal` and `italic` - `style: ['italic','normal']`: An array of 2 values for `next/font/google` - the values are from `normal` and `italic`
### `subsets` ### `subsets`
The font [`subsets`](https://fonts.google.com/knowledge/glossary/subsetting) defined by an array of string values with the names of each subset you would like to be [preloaded](/docs/basic-features/font-optimization#specifying-a-subset). Fonts specified via `subsets` will have a link preload tag injected into the head when the [`preload`](/docs/api-reference/next/font.md#preload) option is true, which is the default. The font [`subsets`](https://fonts.google.com/knowledge/glossary/subsetting) defined by an array of string values with the names of each subset you would like to be [preloaded](/docs/basic-features/font-optimization#specifying-a-subset). Fonts specified via `subsets` will have a link preload tag injected into the head when the [`preload`](/docs/api-reference/next/font.md#preload) option is true, which is the default.
Used in `@next/font/google` Used in `next/font/google`
- Optional - Optional
...@@ -97,7 +98,7 @@ Examples: ...@@ -97,7 +98,7 @@ Examples:
Some variable fonts have extra `axes` that can be included. By default, only the font weight is included to keep the file size down. The possible values of `axes` depend on the specific font. Some variable fonts have extra `axes` that can be included. By default, only the font weight is included to keep the file size down. The possible values of `axes` depend on the specific font.
Used in `@next/font/google` Used in `next/font/google`
- Optional - Optional
...@@ -109,19 +110,19 @@ Examples: ...@@ -109,19 +110,19 @@ Examples:
The font [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) with possible string [values](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display#values) of `'auto'`, `'block'`, `'swap'`, `'fallback'` or `'optional'` with default value of `'swap'`. The font [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) with possible string [values](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display#values) of `'auto'`, `'block'`, `'swap'`, `'fallback'` or `'optional'` with default value of `'swap'`.
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
- Optional - Optional
Examples: Examples:
- `display: 'swap'`: A string assigned to the `swap` value - `display: 'optional'`: A string assigned to the `optional` value
### `preload` ### `preload`
A boolean value that specifies whether the font should be [preloaded](/docs/basic-features/font-optimization#preloading) or not. The default is `true`. A boolean value that specifies whether the font should be [preloaded](/docs/basic-features/font-optimization#preloading) or not. The default is `true`.
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
- Optional - Optional
...@@ -135,7 +136,7 @@ The fallback font to use if the font cannot be loaded. An array of strings of fa ...@@ -135,7 +136,7 @@ The fallback font to use if the font cannot be loaded. An array of strings of fa
- Optional - Optional
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
Examples: Examples:
...@@ -143,23 +144,23 @@ Examples: ...@@ -143,23 +144,23 @@ Examples:
### `adjustFontFallback` ### `adjustFontFallback`
- For `@next/font/google`: A boolean value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The default is `true`. - For `next/font/google`: A boolean value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The default is `true`.
- For `@next/font/local`: A string or boolean `false` value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The possible values are `'Arial'`, `'Times New Roman'` or `false`. The default is `'Arial'`. - For `next/font/local`: A string or boolean `false` value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The possible values are `'Arial'`, `'Times New Roman'` or `false`. The default is `'Arial'`.
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
- Optional - Optional
Examples: Examples:
- `adjustFontFallback: false`: for ``@next/font/google` - `adjustFontFallback: false`: for ``next/font/google`
- `adjustFontFallback: 'Times New Roman'`: for `@next/font/local` - `adjustFontFallback: 'Times New Roman'`: for `next/font/local`
### `variable` ### `variable`
A string value to define the CSS variable name to be used if the style is applied with the [CSS variable method](#css-variables). A string value to define the CSS variable name to be used if the style is applied with the [CSS variable method](#css-variables).
Used in `@next/font/google` and `@next/font/local` Used in `next/font/google` and `next/font/local`
- Optional - Optional
...@@ -171,7 +172,7 @@ Examples: ...@@ -171,7 +172,7 @@ Examples:
An array of font face [descriptor](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face#descriptors) key-value pairs that define the generated `@font-face` further. An array of font face [descriptor](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face#descriptors) key-value pairs that define the generated `@font-face` further.
Used in `@next/font/local` Used in `next/font/local`
- Optional - Optional
...@@ -211,7 +212,7 @@ In addition to importing the font, also import the CSS file where the CSS variab ...@@ -211,7 +212,7 @@ In addition to importing the font, also import the CSS file where the CSS variab
```js ```js
// pages/index.js // pages/index.js
import { Inter } from '@next/font/google' import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css' import styles from '../styles/component.module.css'
const inter = Inter({ const inter = Inter({
...@@ -251,8 +252,8 @@ Then, specify your font definitions as follows: ...@@ -251,8 +252,8 @@ Then, specify your font definitions as follows:
```ts ```ts
// styles/fonts.ts // styles/fonts.ts
import { Inter, Lora, Source_Sans_Pro } from '@next/font/google'; import { Inter, Lora, Source_Sans_Pro } from 'next/font/google';
import localFont from '@next/font/local'; import localFont from 'next/font/local';
// define your variable fonts // define your variable fonts
const inter = Inter(); const inter = Inter();
......
--- ---
description: Optimizing loading web fonts with the built-in `@next/font` loaders. description: Optimizing loading web fonts with the built-in `next/font` loaders.
--- ---
# Optimizing Fonts # Optimizing Fonts
[**`@next/font`**](/docs/api-reference/next/font.md) will automatically optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance. [**`next/font`**](/docs/api-reference/next/font.md) will automatically optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance.
> **🎥 Watch:** Learn more about how to use `@next/font` → [YouTube (6 minutes)](https://www.youtube.com/watch?v=L8_98i_bMMA). > **🎥 Watch:** Learn more about how to use `next/font` → [YouTube (6 minutes)](https://www.youtube.com/watch?v=L8_98i_bMMA).
## Overview ## Overview
`@next/font` includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with zero layout shift, thanks to the underlying CSS `size-adjust` property used. `next/font` includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with zero layout shift, thanks to the underlying CSS `size-adjust` property used.
This new font system also allows you to conveniently use all Google Fonts with performance and privacy in mind. CSS and font files are downloaded at build time and self-hosted with the rest of your static assets. **No requests are sent to Google by the browser.** This new font system also allows you to conveniently use all Google Fonts with performance and privacy in mind. CSS and font files are downloaded at build time and self-hosted with the rest of your static assets. **No requests are sent to Google by the browser.**
## Usage
To get started, install `@next/font`:
```bash
npm install @next/font
```
### Google Fonts ### Google Fonts
Automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment. **No requests are sent to Google by the browser.** Automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment. **No requests are sent to Google by the browser.**
Import the font you would like to use from `@next/font/google` as a function. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility. To get started, import the font you would like to use from `next/font/google` as a function. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.
To use the font in all your pages, add it to [`_app.js` file](https://nextjs.org/docs/advanced-features/custom-app) under `/pages` as shown below: To use the font in all your pages, add it to [`_app.js` file](https://nextjs.org/docs/advanced-features/custom-app) under `/pages` as shown below:
```js ```js
// pages/_app.js // pages/_app.js
import { Inter } from '@next/font/google' import { Inter } from 'next/font/google'
// If loading a variable font, you don't need to specify the font weight // If loading a variable font, you don't need to specify the font weight
const inter = Inter({ subsets: ['latin'] }) const inter = Inter({ subsets: ['latin'] })
...@@ -50,7 +42,7 @@ If you can't use a variable font, you will **need to specify a weight**: ...@@ -50,7 +42,7 @@ If you can't use a variable font, you will **need to specify a weight**:
```js ```js
// pages/_app.js // pages/_app.js
import { Roboto } from '@next/font/google' import { Roboto } from 'next/font/google'
const roboto = Roboto({ const roboto = Roboto({
weight: '400', weight: '400',
...@@ -82,7 +74,7 @@ You can also use the font without a wrapper and `className` by injecting it insi ...@@ -82,7 +74,7 @@ You can also use the font without a wrapper and `className` by injecting it insi
```js ```js
// pages/_app.js // pages/_app.js
import { Inter } from '@next/font/google' import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] }) const inter = Inter({ subsets: ['latin'] })
...@@ -106,7 +98,7 @@ To use the font on a single page, add it to the specific page as shown below: ...@@ -106,7 +98,7 @@ To use the font on a single page, add it to the specific page as shown below:
```js ```js
// pages/index.js // pages/index.js
import { Inter } from '@next/font/google' import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] }) const inter = Inter({ subsets: ['latin'] })
...@@ -139,7 +131,7 @@ This can be done in 2 ways: ...@@ -139,7 +131,7 @@ This can be done in 2 ways:
module.exports = { module.exports = {
experimental: { experimental: {
fontLoaders: [ fontLoaders: [
{ loader: '@next/font/google', options: { subsets: ['latin'] } }, { loader: 'next/font/google', options: { subsets: ['latin'] } },
], ],
}, },
} }
...@@ -151,11 +143,11 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontgoogle) f ...@@ -151,11 +143,11 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontgoogle) f
### Local Fonts ### Local Fonts
Import `@next/font/local` and specify the `src` of your local font file. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility. Import `next/font/local` and specify the `src` of your local font file. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.
```js ```js
// pages/_app.js // pages/_app.js
import localFont from '@next/font/local' import localFont from 'next/font/local'
// Font files can be colocated inside of `pages` // Font files can be colocated inside of `pages`
const myFont = localFont({ src: './my-font.woff2' }) const myFont = localFont({ src: './my-font.woff2' })
...@@ -202,13 +194,13 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontlocal) fo ...@@ -202,13 +194,13 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontlocal) fo
## With Tailwind CSS ## With Tailwind CSS
`@next/font` can be used with Tailwind CSS through a [CSS variable](/docs/api-reference/next/font#css-variables). `next/font` can be used with Tailwind CSS through a [CSS variable](/docs/api-reference/next/font#css-variables).
In the example below, we use the font `Inter` from `@next/font/google` (You can use any font from Google or Local Fonts). Load your font with the `variable` option to define your CSS variable name and assign it to `inter`. Then, use `inter.variable` to add the CSS variable to your HTML document. In the example below, we use the font `Inter` from `next/font/google` (You can use any font from Google or Local Fonts). Load your font with the `variable` option to define your CSS variable name and assign it to `inter`. Then, use `inter.variable` to add the CSS variable to your HTML document.
```js ```js
// pages/_app.js // pages/_app.js
import { Inter } from '@next/font/google' import { Inter } from 'next/font/google'
const inter = Inter({ const inter = Inter({
subsets: ['latin'], subsets: ['latin'],
......
...@@ -425,7 +425,7 @@ ...@@ -425,7 +425,7 @@
"path": "/docs/api-reference/next/server.md" "path": "/docs/api-reference/next/server.md"
}, },
{ {
"title": "@next/font", "title": "next/font",
"path": "/docs/api-reference/next/font.md" "path": "/docs/api-reference/next/font.md"
}, },
{ {
......
...@@ -341,7 +341,7 @@ module.exports = createJestConfig(customJestConfig) ...@@ -341,7 +341,7 @@ module.exports = createJestConfig(customJestConfig)
Under the hood, `next/jest` is automatically configuring Jest for you, including: Under the hood, `next/jest` is automatically configuring Jest for you, including:
- Setting up `transform` using [SWC](https://nextjs.org/docs/advanced-features/compiler) - Setting up `transform` using [SWC](https://nextjs.org/docs/advanced-features/compiler)
- Auto mocking stylesheets (`.css`, `.module.css`, and their scss variants), image imports and [`@next/font`](https://nextjs.org/docs/basic-features/font-optimization) - Auto mocking stylesheets (`.css`, `.module.css`, and their scss variants), image imports and [`next/font`](https://nextjs.org/docs/basic-features/font-optimization)
- Loading `.env` (and all variants) into `process.env` - Loading `.env` (and all variants) into `process.env`
- Ignoring `node_modules` from test resolving and transforms - Ignoring `node_modules` from test resolving and transforms
- Ignoring `.next` from test resolving - Ignoring `.next` from test resolving
......
...@@ -73,9 +73,9 @@ The behavior of [`next/script`](/docs/api-reference/next/script.md) has been upd ...@@ -73,9 +73,9 @@ The behavior of [`next/script`](/docs/api-reference/next/script.md) has been upd
### Font Optimization ### Font Optimization
Previously, Next.js helped you optimize fonts by inlining font CSS. Version 13 introduces the new [`@next/font`](/docs/basic-features/font-optimization.md) module which gives you the ability to customize your font loading experience while still ensuring great performance and privacy. Previously, Next.js helped you optimize fonts by inlining font CSS. Version 13 introduces the new [`next/font`](/docs/basic-features/font-optimization.md) module which gives you the ability to customize your font loading experience while still ensuring great performance and privacy.
See [Optimizing Fonts](/docs/basic-features/font-optimization.md) to learn how to use `@next/font`. See [Optimizing Fonts](/docs/basic-features/font-optimization.md) to learn how to use `next/font`.
## Upgrading to 12.2 ## Upgrading to 12.2
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment