Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

font api updates #42724

Merged
merged 6 commits into from Nov 10, 2022
Merged

font api updates #42724

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1a4c944
font api updates
ismaelrumzan Nov 10, 2022
27195af
added tailwind to font optimization
ismaelrumzan Nov 10, 2022
b8a1150
tweak wording
ismaelrumzan Nov 10, 2022
665a43f
Merge branch 'canary' into v13-docs-fonts-update2
ismaelrumzan Nov 10, 2022
6fdc28e
wording update
ismaelrumzan Nov 10, 2022
ad4f58a
Merge branch 'v13-docs-fonts-update2' of https://github.com/ismaelrum…
ismaelrumzan Nov 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
169 changes: 92 additions & 77 deletions docs/api-reference/next/font.md
View file
Open in desktop
Expand Up @@ -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:
Expand Down
45 changes: 45 additions & 0 deletions docs/basic-features/font-optimization.md
View file
Open in desktop
Expand Up @@ -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:
Expand Down