diff --git a/docs/basic-features/font-optimization.md b/docs/basic-features/font-optimization.md index 8965d97a26..1dd5d9326a 100644 --- a/docs/basic-features/font-optimization.md +++ b/docs/basic-features/font-optimization.md @@ -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 + + +``` + ## Related For more information on what to do next, we recommend the following sections: