Unverified Commit 2df817ce authored by Janicklas Ralph's avatar Janicklas Ralph Committed by GitHub

Docs for experimental font optimization `adjustFontFallbacks` (#40771)



## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see `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`
- [ ] Integration 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`

## Documentation / Examples

- [ ] Make sure the linting passes by running `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 8659d6f8
......@@ -65,6 +65,58 @@ module.exports = {
}
```
## Optimize CLS for Fonts
Next.js can reduce the Cumulative Layout Shift ([CLS](https://web.dev/cls/)) of your website by adjusting the size of your fallback fonts and inlining the font CSS.
Sites that load fonts with `font-display: swap` usually suffer from ([CLS](https://web.dev/cls/)) when the web font loads and replaces the fallback font. This is due to differences in height, width, and alignment between the main and fallback fonts, which is common even if the CSS font size is the same.
Next.js can reduce CLS automatically by adjusting the size of the fallback font to match that of the main font using font override metric properties such as `size-adjust`, `ascent-override`, `descent-override`, and `line-gap-override`.
To enable this experimental feature, update your `next.config.js` with the following configuration:
```js
module.exports = {
experimental: {
adjustFontFallbacks: true,
},
}
```
When enabled, Next.js will generate a fallback font definition with the correct size overrides in the format `{fontName} Fallback`.
For example, the font `Inter` will generate the fallback font `Inter Fallback`.
You can then use the fallback font in your stylesheets such as the following:
```css
body {
font-family: 'Inter', 'Inter Fallback', sans-serif;
}
```
> **NOTE**: Next.js currently supports one cross-platform serif font ('Times New Roman') and one cross-platform sans-serif font ('Arial')
The final output will include the fallback override definition.
```html
// Injected into index.html during build/render
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<style data-href="https://fonts.googleapis.com/css2?family=Inter&display=swap">
@font-face{
font-family: 'Inter';
font-style:normal
...
}
@font-face {
font-family: 'Inter Fallback',
src: local('Arial');
ascent-override: 96.975%;
...
}
</style>
```
## Related
For more information on what to do next, we recommend the following sections:
......
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