diff --git a/docs/api-reference/next/font.md b/docs/api-reference/next/font.md index ddc6836b7ca3e4f..77cb2caa28aa844 100644 --- a/docs/api-reference/next/font.md +++ b/docs/api-reference/next/font.md @@ -13,157 +13,172 @@ description: Optimizing loading web fonts with the built-in `@next/font` loaders -This API reference will help you understand how to use [`@next/font/google`](#nextfontgoogle) and [`@next/font/local`](#nextfontlocal). For features and usage, please see the [Optimizing Fonts](/docs/basic-features/font-optimization.md) page. - -## @next/font/google +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 -For usage, review [Google Fonts](/docs/basic-features/font-optimization.md#google-fonts). +For usage, review [Google Fonts](/docs/basic-features/font-optimization.md#google-fonts) and [Local Fonts](/docs/basic-features/font-optimization#local-fonts). + +| Key | `font/google` | `font/local` | Data type | Required | +| ------------------------------------------- | ------------- | ------------ | -------------------------- | ----------------- | +| [`src`](#src) | ❌ | ✅ | String or Array of Objects | Required | +| [`weight`](#weight) | ✅ | ✅ | String or Array | Required/Optional | +| [`style`](#style) | ✅ | ✅ | String or Array | Optional | +| [`subsets`](#subsets) | ✅ | ❌ | Array of Strings | Optional | +| [`axes`](#axes) | ✅ | ❌ | Array of Strings | Optional | +| [`display`](#display) | ✅ | ✅ | String | Optional | +| [`preload`](#preload) | ✅ | ✅ | Boolean | Optional | +| [`fallback`](#fallback) | ✅ | ✅ | Array of Strings | Optional | +| [`adjustFontFallback`](#adjustFontFallback) | ✅ | ✅ | Boolean or String | Optional | +| [`variable`](#variable) | ✅ | ✅ | String | Optional | +| [`declarations`](#declarations) | ❌ | ✅ | Array of Objects | Optional | -| Key | Example | Data type | Required | -| ------------------------------------------- | ---------------------------------- | --------------------------------------------------------- | ------------------------------------------------ | -| [`weight`](#weight) | `weight: '600'` | String | Required if font is not variable | -| [`style`](#style) | `style: 'italic'` | String | Optional | -| [`subsets`](#subsets) | `subsets: ['latin']` | Array of Strings | Optional | -| [`axes`](#axes) | `axes: ['slnt']` | Array of Strings based on the available axes for the font | Optional for variable fonts that have extra axes | -| [`display`](#display) | `display: 'swap'` | String | Optional | -| [`preload`](#preload) | `preload: false` | Boolean | Optional | -| [`fallback`](#fallback) | `fallback: ['system-ui', 'arial']` | Array of Strings | Optional | -| [`adjustFontFallback`](#adjustFontFallback) | `adjustFontFallback: false` | Boolean | Optional | -| [`variable`](#variable) | `variable: '--my-font'` | String | Optional | +### `src` -### `weight` +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 font [`weight`](https://fonts.google.com/knowledge/glossary/weight) represented as a string with possible values of the weights available for the specific font. For example, for the font [`Inter`](https://fonts.google.com/specimen/Inter?query=inter), the possible values are `'100'`, `'200'`, `'300'`, `'400'`, `'500'`, `'600'`, `'700'`, `'800'`, `'900'` or `'variable'` (`'variable'` is the default in this case). +Used in `@next/font/local` -- Required if the font being used is **not** [variable](https://fonts.google.com/variablefonts) - -### `style` +- Required -The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with possible string [values](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style#values) of `'normal'` or `'italic'` with default value of `'normal'`. +Examples: -- Optional +- `src:'./fonts/my-font.woff2'` where `my-font.woff2` is placed in a directory named `fonts` inside the `app` directory +- `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',},]` +- if the font loader function is called in `app/page.tsx` using `src:'../styles/fonts/my-font.ttf'`, then `my-font.ttf` is placed in `styles/fonts` at the root of the project -### `subsets` +### `weight` -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.md#specifying-a-subset). Fonts specified via `subsets` will have a link preload tag injected into the head when the [`preload`](#preload) option is true, which is the default. +The font [`weight`](https://fonts.google.com/knowledge/glossary/weight) with the following possibilities: -- Optional +- 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. -### `axes` +Used in `@next/font/google` and `@next/font/local` -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. For example, the `Inter` variable font has `slnt` as additional `axes` as shown [here](https://fonts.google.com/variablefonts?vfquery=inter#font-families). You can find the possible `axes` values for your font by using the filter on the [Google variable fonts page](https://fonts.google.com/variablefonts#font-families) and looking for axes other than `wght`. +- Required if the font being used is **not** [variable](https://fonts.google.com/variablefonts) -- Optional +Examples: -### `display` +- `weight: '400'`: A string for a single weight value - for the font [`Inter`](https://fonts.google.com/specimen/Inter?query=inter), the possible values are `'100'`, `'200'`, `'300'`, `'400'`, `'500'`, `'600'`, `'700'`, `'800'`, `'900'` or `'variable'` where `'variable'` is the default) +- `weight: '100 900'`: A string for the range between `100` and `900` for a variable font +- `weight: ['100','400','900']`: An array of 3 possible values for a non variable font -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 `'optional'`. +### `style` -- Optional +The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with the following possibilities: -### `preload` +- 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. -A boolean value that specifies whether the font should be [preloaded](/docs/basic-features/font-optimization.md#preloading) or not. The default is `true`. +Used in `@next/font/google` and `@next/font/local` - Optional -### `fallback` +Examples: -The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts such as `['system-ui', 'arial']` with no default. +- `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: ['italic','normal']`: An array of 2 values for `@next/font/google` - the values are from `normal` and `italic` -- Optional +### `subsets` -### `adjustFontFallback` +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/optimizing/fonts.md#specifying-a-subset). Fonts specified via `subsets` will have a link preload tag injected into the head when the [`preload`](/docs/api-reference/components/font.md#preload) option is true, which is the default. -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`. +Used in `@next/font/google` - Optional -### `variable` +Examples: -A string value to define the CSS variable name to be used if the style is applied with the [CSS variable method](#css-variables). +- `subsets: ['latin']`: An array with the subset `latin` -- Optional +### `axes` -## @next/font/local +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. -### Font function arguments +Used in `@next/font/google` -For usage, review [Local Fonts](/docs/basic-features/font-optimization.md#local-fonts). +- Optional -| Key | Example | Data type | Required | -| ------------------------------------------- | ----------------------------------------------------------- | -------------------------------------- | -------- | -| [`src`](#src) | `src: './my-font.woff2'` | String | Required | -| [`weight`](#weight) | `weight: '600' or '100 900'` | String | Optional | -| [`style`](#style) | `style: 'italic'` | String | Optional | -| [`display`](#display) | `display: 'swap'` | String | Optional | -| [`preload`](#preload) | `preload: false` | Boolean | Optional | -| [`fallback`](#fallback) | `fallback: ['system-ui', 'arial']` | Array of Strings | Optional | -| [`adjustFontFallback`](#adjustFontFallback) | `adjustFontFallback: false` | ['Arial', 'Times New Roman', false] | Optional | -| [`variable`](#variable) | `variable: '--my-font'` | String | Optional | -| [`declarations`](#declarations) | `declarations: [{ prop: 'ascent-override', value: '90%' }]` | Array<{ prop: string; value: string }> | Optional | +Examples: -### `src` +- `axes: ['slnt']`: An array with value `slnt` for the `Inter` variable font which has `slnt` as additional `axes` as shown [here](https://fonts.google.com/variablefonts?vfquery=inter#font-families). You can find the possible `axes` values for your font by using the filter on the [Google variable fonts page](https://fonts.google.com/variablefonts#font-families) and looking for axes other than `wght` -The path of the font file as a string relative to the directory where the font loader function is called or to the `pages` directory. +### `display` -- Required +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 `'optional'`. -Examples are: +Used in `@next/font/google` and `@next/font/local` -- `'./fonts/my-font.woff2'` where `my-font.woff2` is placed in a directory named `fonts` inside the `pages` directory -- if the font loader function is called in `pages/index.js` using `'../styles/fonts/my-font.ttf'`, then `my-font.ttf` is placed in `styles/fonts` at the root of the project +- Optional -### `weight` +Examples: -The font [`weight`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight) either as a specific weight string value such as `'400'` or a range of values if it's a variable font such as `'100 900'`. +- `display: 'swap'`: A string assigned to the `swap` value -- Optional +### `preload` -### `style` +A boolean value that specifies whether the font should be [preloaded](/docs/optimizing/fonts#preloading) or not. The default is `true`. -The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with possible string [values](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style#values) of `'normal'`, `'italic'` or `'oblique'` with default value of `'normal'`. +Used in `@next/font/google` and `@next/font/local` - Optional -### `display` +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 `'optional'`. - -- Optional +- `preload: false` -### `preload` +### `fallback` -A boolean value that specifies whether the font should be [preloaded](/docs/basic-features/font-optimization.md#preloading) or not. The default is `true`. +The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts with no default. - Optional -### `fallback` +Used in `@next/font/google` and `@next/font/local` -The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts such as `['system-ui', 'arial']` with no default. +Examples: -- Optional +- `fallback: ['system-ui', 'arial']`: An array setting the fallback fonts to `system-ui` or `arial` ### `adjustFontFallback` -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/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'`. + +Used in `@next/font/google` and `@next/font/local` - Optional +Examples: + +- `adjustFontFallback: false`: for ``@next/font/google` +- `adjustFontFallback: 'Times New Roman'`: for `@next/font/local` + ### `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). +Used in `@next/font/google` and `@next/font/local` + - Optional +Examples: + +- `variable: '--my-font'`: The CSS variable `--my-font` is declared + ### `declarations` -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 such as `{ prop: 'ascent-override', value: '90%' }`. +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` - Optional +Examples: + +- `declarations: [{ prop: 'ascent-override', value: '90%' }]` + ## Applying Styles You can apply the font styles in three ways: diff --git a/docs/basic-features/font-optimization.md b/docs/basic-features/font-optimization.md index ebbf1f075560585..b2dc1c8421573a8 100644 --- a/docs/basic-features/font-optimization.md +++ b/docs/basic-features/font-optimization.md @@ -158,6 +158,51 @@ export default function MyApp({ Component, pageProps }) { View the [Font API Reference](/docs/api-reference/next/font.md#nextfontlocal) for more information. +## With Tailwind CSS + +`@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. + +```js +// pages/_app.js +import { Inter } from '@next/font/google' + +const inter = Inter({ + variable: '--font-inter', +}) + +export default function MyApp({ Component, pageProps }) { + return ( +
+ +
+ ) +} +``` + +Finally, add the CSS variable to your [Tailwind CSS config](https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss): + +```js +// tailwind.config.js +const { fontFamily } = require('tailwindcss/defaultTheme') + +/** @type {import('tailwindcss').Config} \*/ +module.exports = { + content: ['./app/**/*.{js,ts,jsx,tsx}'], + theme: { + extend: { + fontFamily: { + sans: ['var(--font-inter)', ...fontFamily.sans], + }, + }, + }, + plugins: [], +} +``` + +You can now use the `font-sans` utility class to apply the font to your elements. + ## Preloading When a font function is called on a page of your site, it is not globally available and preloaded on all routes. Rather, the font is only preloaded on the related route/s based on the type of file where it is used: