Version | Changes |
---|---|
v13.2.0 | @next/font renamed to next/font . Installation no longer required. |
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 and Local Fonts.
Key | font/google | font/local | Data type | Required |
---|---|---|---|---|
src | ❌ | ✅ | String or Array of Objects | Required |
weight | ✅ | ✅ | String or Array | Required/Optional |
style | ✅ | ✅ | String or Array | Optional |
subsets | ✅ | ❌ | Array of Strings | Optional |
axes | ✅ | ❌ | Array of Strings | Optional |
display | ✅ | ✅ | String | Optional |
preload | ✅ | ✅ | Boolean | Optional |
fallback | ✅ | ✅ | Array of Strings | Optional |
adjustFontFallback | ✅ | ✅ | Boolean or String | Optional |
variable | ✅ | ✅ | String | Optional |
declarations | ❌ | ✅ | Array of Objects | Optional |
src
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.
Used in next/font/local
Examples:
src:'./fonts/my-font.woff2'
where my-font.woff2
is placed in a directory named fonts
inside the app
directorysrc:[{path: './inter/Inter-Thin.ttf', weight: '100',},{path: './inter/Inter-Regular.ttf',weight: '400',},{path: './inter/Inter-Bold-Italic.ttf', weight: '700',style: 'italic',},]
app/page.tsx
using src:'../styles/fonts/my-font.ttf'
, then my-font.ttf
is placed in styles/fonts
at the root of the projectweight
The font weight
with the following possibilities:
next/font/google
only.Used in next/font/google
and next/font/local
Examples:
weight: '400'
: A string for a single weight value - for the font 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 fontweight: ['100','400','900']
: An array of 3 possible values for a non variable fontstyle
The font style
with the following possibilities:
'normal'
next/font/google
only.Used in next/font/google
and next/font/local
Examples:
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 stylesstyle: ['italic','normal']
: An array of 2 values for next/font/google
- the values are from normal
and italic
subsets
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.
Used in next/font/google
Examples:
subsets: ['latin']
: An array with the subset latin
axes
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.
Used in next/font/google
Examples:
axes: ['slnt']
: An array with value slnt
for the Inter
variable font which 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
display
The font display
with possible string values of 'auto'
, 'block'
, 'swap'
, 'fallback'
or 'optional'
with default value of 'swap'
.
Used in next/font/google
and next/font/local
Examples:
display: 'optional'
: A string assigned to the optional
valuepreload
A boolean value that specifies whether the font should be preloaded or not. The default is true
.
Used in next/font/google
and next/font/local
Examples:
preload: false
fallback
The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts with no default.
Used in next/font/google
and next/font/local
Examples:
fallback: ['system-ui', 'arial']
: An array setting the fallback fonts to system-ui
or arial
adjustFontFallback
next/font/google
: A boolean value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The default is true
.next/font/local
: 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'
.Used in next/font/google
and next/font/local
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.
Used in next/font/google
and next/font/local
Examples:
variable: '--my-font'
: The CSS variable --my-font
is declareddeclarations
An array of font face descriptor key-value pairs that define the generated @font-face
further.
Used in next/font/local
Examples:
declarations: [{ prop: 'ascent-override', value: '90%' }]
You can apply the font styles in three ways:
className
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>
style
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
.