Skip to content

Commit

Permalink
font api updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@ismaelrumzan
ismaelrumzan committed Nov 10, 2022
1 parent 3174c73 commit 1a4c944
Showing 1 changed file with 92 additions and 77 deletions.
169 changes: 92 additions & 77 deletions docs/api-reference/next/font.md
View file
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

0 comments on commit 1a4c944

Please sign in to comment.