From e57edff9690c6ec9db6634dee0eb44a7013a46a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hannes=20Born=C3=B6?= Date: Fri, 16 Dec 2022 07:58:08 +0100 Subject: [PATCH] docs: Add explanation about font-display (#44001) Add explanation and recommendation of `font-display`. ## Bug - [ ] Related issues linked using `fixes #number` - [ ] Integration tests added - [ ] Errors have a helpful link attached, see [`contributing.md`](https://github.com/vercel/next.js/blob/canary/contributing.md) ## 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 - [ ] 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: JJ Kasper <22380829+ijjk@users.noreply.github.com> --- docs/basic-features/font-optimization.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/basic-features/font-optimization.md b/docs/basic-features/font-optimization.md index f0db4c0c72f8..9442be7bb646 100644 --- a/docs/basic-features/font-optimization.md +++ b/docs/basic-features/font-optimization.md @@ -22,6 +22,12 @@ To get started, install `@next/font`: npm install @next/font ``` +### Choosing font-display + +[`font-display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) lets you to control how your font is displayed while it's loading. `@next/font` uses `font-display: optional` by default. When the primary font used by `@next/font` does not load within 100ms, the auto generated fallback font will be displayed in the browser. While it is automatically generated to be as visually similar to the primary font as possible to reduce layout shift, it does come with the tradeoff that your intended font might not be shown on slower networks unless it's cached. + +If you want guarantees around your intended font always showing, and accept the tradeoff of minimal layout shift from swapping your fallback font for the primary font, you can [use `font-display: swap`](/docs/api-reference/next/font.md#display). + ### 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.**