0
# Local Fonts
1
2
Universal font loader for custom font files with automatic fallback generation and optimal loading performance. Supports all major font formats and provides comprehensive configuration options.
3
4
## Capabilities
5
6
### Local Font Function
7
8
```typescript { .api }
9
/**
10
* Load custom local font files with optimal performance
11
* @param options - Local font configuration
12
* @returns Font object with className, style, and optional variable property
13
*/
14
function localFont<T extends CssVariable | undefined = undefined>(
15
options: LocalFont<T>
16
): T extends undefined ? NextFont : NextFontWithVariable;
17
```
18
19
### Local Font Configuration
20
21
```typescript { .api }
22
interface LocalFont<T extends CssVariable | undefined = undefined> {
23
src: string | Array<{
24
path: string;
25
weight?: string;
26
style?: string;
27
}>;
28
display?: Display;
29
weight?: string;
30
style?: string;
31
adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
32
fallback?: string[];
33
preload?: boolean;
34
variable?: T;
35
declarations?: Array<{ prop: string; value: string }>;
36
}
37
```
38
39
### Source Configuration
40
41
The `src` property accepts either a single font file or an array of font files with different weights and styles.
42
43
#### Single Font File
44
45
```typescript { .api }
46
src: string;
47
```
48
49
Path to a single font file. All font formats are supported (woff2, woff, ttf, otf, eot).
50
51
#### Multiple Font Files
52
53
```typescript { .api }
54
src: Array<{
55
path: string;
56
weight?: string;
57
style?: string;
58
}>;
59
```
60
61
Array of font descriptors for different weights and styles:
62
- **path**: Path to the font file
63
- **weight**: Font weight (e.g., '400', '700', 'bold')
64
- **style**: Font style ('normal', 'italic')
65
66
### Font Properties
67
68
#### Display Property
69
70
```typescript { .api }
71
display?: Display;
72
```
73
74
Controls CSS `font-display` behavior:
75
- **'auto'**: Browser default
76
- **'block'**: Block until font loads
77
- **'swap'**: Show fallback, swap when ready (recommended)
78
- **'fallback'**: Brief block, then fallback
79
- **'optional'**: Use fallback if font loads slowly
80
81
#### Weight and Style
82
83
```typescript { .api }
84
weight?: string;
85
style?: string;
86
```
87
88
Default weight and style for the font family:
89
- **weight**: CSS font-weight value ('400', '700', 'bold', etc.)
90
- **style**: CSS font-style value ('normal', 'italic', 'oblique')
91
92
#### Fallback Configuration
93
94
```typescript { .api }
95
adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
96
fallback?: string[];
97
```
98
99
- **adjustFontFallback**: Automatically calculate fallback metrics using Arial or Times New Roman as reference
100
- **fallback**: Array of fallback font names to use if custom font fails to load
101
102
#### Variable Fonts
103
104
```typescript { .api }
105
variable?: T;
106
```
107
108
CSS custom property name for the font family. Enables using the font via CSS variables.
109
110
#### Preloading
111
112
```typescript { .api }
113
preload?: boolean;
114
```
115
116
Whether to preload the font file for faster initial rendering.
117
118
#### Custom Declarations
119
120
```typescript { .api }
121
declarations?: Array<{ prop: string; value: string }>;
122
```
123
124
Additional CSS properties to include in the @font-face declaration:
125
- **prop**: CSS property name
126
- **value**: CSS property value
127
128
## Usage Examples
129
130
### Single Font File
131
132
```typescript
133
import localFont from "@next/font/local";
134
135
const myFont = localFont({
136
src: './fonts/my-font.woff2',
137
display: 'swap',
138
});
139
140
export default function Page() {
141
return (
142
<div className={myFont.className}>
143
<h1>Custom Font Text</h1>
144
</div>
145
);
146
}
147
```
148
149
### Multiple Font Files (Font Family)
150
151
```typescript
152
import localFont from "@next/font/local";
153
154
const myFontFamily = localFont({
155
src: [
156
{
157
path: './fonts/my-font-regular.woff2',
158
weight: '400',
159
style: 'normal',
160
},
161
{
162
path: './fonts/my-font-italic.woff2',
163
weight: '400',
164
style: 'italic',
165
},
166
{
167
path: './fonts/my-font-bold.woff2',
168
weight: '700',
169
style: 'normal',
170
},
171
],
172
display: 'swap',
173
});
174
```
175
176
### Variable Font with CSS Custom Property
177
178
```typescript
179
import localFont from "@next/font/local";
180
181
const myVariableFont = localFont({
182
src: './fonts/my-variable-font.woff2',
183
variable: '--font-custom',
184
weight: '100 900', // Variable font weight range
185
});
186
187
export default function RootLayout({ children }) {
188
return (
189
<html lang="en" className={myVariableFont.variable}>
190
<body>{children}</body>
191
</html>
192
);
193
}
194
```
195
196
### Fallback Configuration
197
198
```typescript
199
import localFont from "@next/font/local";
200
201
const customSerif = localFont({
202
src: './fonts/custom-serif.woff2',
203
fallback: ['Georgia', 'Times New Roman', 'serif'],
204
adjustFontFallback: 'Times New Roman', // Use Times New Roman metrics for fallback adjustment
205
display: 'swap',
206
});
207
```
208
209
### Font with Custom CSS Declarations
210
211
```typescript
212
import localFont from "@next/font/local";
213
214
const customFont = localFont({
215
src: './fonts/custom-font.woff2',
216
declarations: [
217
{ prop: 'font-feature-settings', value: '"liga" 1, "calt" 1' },
218
{ prop: 'font-variation-settings', value: '"wght" 400' },
219
],
220
});
221
```
222
223
### Preloading Critical Fonts
224
225
```typescript
226
import localFont from "@next/font/local";
227
228
const headingFont = localFont({
229
src: './fonts/heading-font.woff2',
230
preload: true, // Preload for above-the-fold content
231
display: 'block', // Block rendering until font loads
232
});
233
```
234
235
## Supported Font Formats
236
237
@next/font supports all major web font formats:
238
239
### Modern Formats (Recommended)
240
- **WOFF2** (.woff2) - Best compression, widely supported
241
- **WOFF** (.woff) - Good compression, universal support
242
243
### Legacy Formats
244
- **TrueType** (.ttf) - Uncompressed, large file sizes
245
- **OpenType** (.otf) - Supports advanced typography features
246
- **EOT** (.eot) - Internet Explorer legacy support
247
248
## Font File Organization
249
250
### Recommended Structure
251
252
```
253
public/
254
fonts/
255
my-font-regular.woff2
256
my-font-bold.woff2
257
my-font-italic.woff2
258
```
259
260
### Relative Path Usage
261
262
Font paths are relative to the `public` directory:
263
264
```typescript
265
const myFont = localFont({
266
src: './fonts/my-font.woff2', // Resolves to public/fonts/my-font.woff2
267
});
268
```
269
270
## Performance Optimization
271
272
### Format Priority
273
1. **WOFF2**: Use as primary format for best compression
274
2. **WOFF**: Use as fallback for older browsers
275
3. **TTF/OTF**: Avoid in production due to large file sizes
276
277
### Loading Strategy
278
- **Preload**: Critical fonts used above the fold
279
- **Swap display**: Non-critical fonts to prevent render blocking
280
- **Subset fonts**: Remove unused characters to reduce file size
281
- **Variable fonts**: Single file for multiple weights/styles
282
283
### Fallback Optimization
284
```typescript
285
const optimizedFont = localFont({
286
src: './fonts/custom-font.woff2',
287
adjustFontFallback: 'Arial', // Prevents layout shift
288
fallback: ['system-ui', 'Arial', 'sans-serif'],
289
display: 'swap',
290
});
291
```
292
293
## Error Handling
294
295
Local fonts handle various error scenarios:
296
297
### Missing Font Files
298
- Development: Shows error message with file path
299
- Production: Falls back to specified fallback fonts
300
301
### Invalid Font Formats
302
- Unsupported formats are ignored
303
- Falls back to next format in the array or fallback fonts
304
305
### Network Issues
306
- Self-hosted fonts avoid external network dependencies
307
- Files served from Next.js static assets