font api updates (#42724)

Update the next fonts API reference to match the latest changes from [beta.nextjs.org](https://beta.nextjs.org/docs/api-reference/components/font) ## 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 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)
vercel · Nov 10, 2022 · 29f20d3 · 29f20d3
1 parent 6490252
commit 29f20d3
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 77 deletions.
diff --git 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
 
 </details>
 
-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
@@ -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 (
+    <main className={inter.variable}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+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: