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 app
directory.
- Required
Examples are:
'./fonts/my-font.woff2'
wheremy-font.woff2
is placed in a directory namedfonts
inside theapp
directory- if the font loader function is called in
app/page.tsx
using'../styles/fonts/my-font.ttf'
, thenmy-font.ttf
is placed instyles/fonts
at 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:
// app/page.tsx
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.
// app/page.tsx
<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
.