| description |
|---|
Optimizing loading web fonts with the built-in `@next/font` loaders. |
Version History
| Version | Changes |
|---|---|
v13.0.0 |
@next/font was added. |
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 page.
For usage, review Google Fonts.
| Key | Example | Data type | Required |
|---|---|---|---|
weight |
weight: '600' |
String | Required if font is not variable |
style |
style: 'italic' |
String | Optional |
subsets |
subsets: ['latin'] |
Array of Strings | Optional |
axes |
axes: ['slnt'] |
Array of Strings based on the available axes for the font | Optional for variable fonts that have extra axes |
display |
display: 'swap' |
String | Optional |
preload |
preload: false |
Boolean | Optional |
fallback |
fallback: ['system-ui', 'arial'] |
Array of Strings | Optional |
adjustFontFallback |
adjustFontFallback: false |
Boolean | Optional |
variable |
variable: '--my-font' |
String | Optional |
The font weight represented as a string with possible values of the weights available for the specific font. For example, for the font Inter, the possible values are '100', '200', '300', '400', '500', '600', '700', '800', '900' or 'variable' ('variable' is the default in this case).
- Required if the font being used is not variable
The font style with possible string values of 'normal' or 'italic' with default value of 'normal'.
- Optional
The font subsets defined by an Array of string values with the names of each subset you would like to be preloaded. Fonts specified via subsets will have a link preload tag injected into the head when the preload option is true, which is the default.
- Optional
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. You can find the possible axes values for your font by using the filter on the Google variable fonts page and looking for axes other than wght.
- Optional
The font display with possible string values of 'auto', 'block', 'swap', 'fallback' or 'optional' with default value of 'optional'.
- Optional
A boolean value that specifies whether the font should be preloaded or not. The default is true.
- Optional
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.
- Optional
A boolean value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The default is true.
- Optional
A string value to define the CSS variable name to be used if the style is applied with the CSS variable method.
- Optional
For usage, review Local Fonts.
| Key | Example | Data type | Required |
|---|---|---|---|
src |
src: './my-font.woff2' |
String | Required |
weight |
weight: '600' or '100 900' |
String | Optional |
style |
style: 'italic' |
String | Optional |
display |
display: 'swap' |
String | Optional |
preload |
preload: false |
Boolean | Optional |
fallback |
fallback: ['system-ui', 'arial'] |
Array of Strings | Optional |
adjustFontFallback |
adjustFontFallback: false |
['Arial', 'Times New Roman', false] | Optional |
variable |
variable: '--my-font' |
String | Optional |
declarations |
declarations: [{ prop: 'ascent-override', value: '90%' }] |
Array<{ prop: string; value: string }> | Optional |
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.
- Required
Examples are:
'./fonts/my-font.woff2'wheremy-font.woff2is placed in a directory namedfontsinside thepagesdirectory- if the font loader function is called in
pages/index.jsusing'../styles/fonts/my-font.ttf', thenmy-font.ttfis placed instyles/fontsat the root of the project
The 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'.
- Optional
The font style with possible string values of 'normal', 'italic' or 'oblique' with default value of 'normal'.
- Optional
The font display with possible string values of 'auto', 'block', 'swap', 'fallback' or 'optional' with default value of 'optional'.
- Optional
A boolean value that specifies whether the font should be preloaded or not. The default is true.
- Optional
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.
- Optional
A string or boolean false value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The possible values are 'Arial', 'Times New Roman' or false. The default is 'Arial'.
- Optional
A string value to define the CSS variable name to be used if the style is applied with the CSS variable method.
- Optional
An array of font face descriptor key-value pairs that define the generated @font-face further such as { prop: 'ascent-override', value: '90%' }.
- Optional
You can apply the font styles in three ways:
Returns a read-only CSS className for the loaded font to be passed to an HTML element.
<p className={inter.className}>Hello, Next.js!</p>Returns a read-only CSS style object for the loaded font to be passed to an HTML element, including style.fontFamily to access the font family name and fallback fonts.
<p style={inter.style}>Hello World</p>If you would like to set your styles in an external style sheet and specify additional options there, use the CSS variable method.
In addition to importing the font, also import the CSS file where the CSS variable is defined and set the variable option of the font loader object as follows:
// pages/index.js
import { Inter } from '@next/font/google'
import styles from '../styles/component.module.css'
const inter = Inter({
variable: '--inter-font',
})To use the font, set the className of the parent container of the text you would like to style to the font loader's variable value and the className of the text to the styles property from the external CSS file.
// pages/index.js
<main className={inter.variable}>
<p className={styles.text}>Hello World</p>
</main>Define the text selector class in the component.module.css CSS file as follows:
/* styles/component.module.css */
.text {
font-family: var(--inter-font);
font-weight: 200;
font-style: italic;
}In the example above, the text Hello World is styled using the Inter font and the generated font fallback with font-weight: 200 and font-style: italic.