0
# Local Fonts
1

2
Local font loading functionality for self-hosted font files with comprehensive configuration options and automatic optimization. Supports multiple font formats, weights, and styles with zero layout shift optimization.
3

4
## Capabilities
5

6
### localFont Function
7

8
Default export function for loading local font files with automatic optimization and fallback generation.
9

10
```typescript { .api }
11
/**
12
 * Load local font files with automatic optimization
13
 * @param options - Local font configuration options
14
 * @returns NextFont or NextFontWithVariable based on variable option
15
 */
16
function localFont<T extends CssVariable | undefined = undefined>(
17
  options: LocalFont<T>
18
): T extends undefined ? NextFont : NextFontWithVariable;
19

20
interface LocalFont<T extends CssVariable | undefined = undefined> {
21
  /** Font file path(s) - single path or array of font variants */
22
  src: string | Array<{
23
    path: string;
24
    weight?: string;
25
    style?: string;
26
  }>;
27
  /** CSS font-display strategy */
28
  display?: Display;
29
  /** Default font weight */
30
  weight?: string;
31
  /** Default font style */
32
  style?: string;
33
  /** Fallback font for metrics adjustment */
34
  adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
35
  /** Fallback font stack */
36
  fallback?: string[];
37
  /** Whether to preload the font */
38
  preload?: boolean;
39
  /** CSS custom property name */
40
  variable?: T;
41
  /** Additional CSS declarations */
42
  declarations?: Array<{ prop: string; value: string }>;
43
}
44
```
45

46
## Configuration Options
47

48
### src
49
**Type**: `string | Array<{ path: string; weight?: string; style?: string }>`  
50
**Description**: Font file path(s). Use string for single font file or array for multiple variants. Supports `.woff2`, `.woff`, `.ttf`, `.otf`, and `.eot` formats (see [Supported Font Formats](#supported-font-formats)).
51

52
**Single Font File:**
53
```typescript
54
const myFont = localFont({
55
  src: './fonts/MyFont-Regular.woff2'
56
});
57
```
58

59
**Multiple Font Files:**
60
```typescript
61
const myFont = localFont({
62
  src: [
63
    {
64
      path: './fonts/MyFont-Light.woff2',
65
      weight: '300',
66
      style: 'normal',
67
    },
68
    {
69
      path: './fonts/MyFont-Regular.woff2',
70
      weight: '400',
71
      style: 'normal',
72
    },
73
    {
74
      path: './fonts/MyFont-Bold.woff2',
75
      weight: '700',
76
      style: 'normal',
77
    },
78
    {
79
      path: './fonts/MyFont-Italic.woff2',
80
      weight: '400',
81
      style: 'italic',
82
    },
83
  ]
84
});
85
```
86

87
### display
88
**Type**: `Display`  
89
**Description**: CSS font-display strategy for loading behavior.
90

91
**Values**: `'auto' | 'block' | 'swap' | 'fallback' | 'optional'`
92

93
### weight
94
**Type**: `string`  
95
**Description**: Default font weight. Used when `src` is a single file.
96

97
### style
98
**Type**: `string`  
99
**Description**: Default font style. Used when `src` is a single file.
100

101
### adjustFontFallback
102
**Type**: `'Arial' | 'Times New Roman' | false`  
103
**Description**: Fallback font to use for automatic metrics adjustment. Helps reduce layout shift by matching fallback font metrics to the web font.
104

105
**Usage Examples:**
106
```typescript
107
// Adjust fallback to match Arial metrics
108
const sansFont = localFont({
109
  src: './fonts/MySansFont.woff2',
110
  adjustFontFallback: 'Arial'
111
});
112

113
// Adjust fallback to match Times New Roman metrics
114
const serifFont = localFont({
115
  src: './fonts/MySerifFont.woff2', 
116
  adjustFontFallback: 'Times New Roman'
117
});
118

119
// Disable automatic adjustment
120
const customFont = localFont({
121
  src: './fonts/MyFont.woff2',
122
  adjustFontFallback: false
123
});
124
```
125

126
### fallback
127
**Type**: `string[]`  
128
**Description**: Fallback font stack for the font family.
129

130
### preload
131
**Type**: `boolean`  
132
**Description**: Whether to preload the font file. Recommended for above-the-fold content.
133

134
### variable
135
**Type**: `` `--${string}` | undefined``  
136
**Description**: CSS custom property name for the font family. When provided, returns `NextFontWithVariable`.
137

138
### declarations
139
**Type**: `Array<{ prop: string; value: string }>`  
140
**Description**: Additional CSS declarations to include with the font face.
141

142
**Usage Examples:**
143
```typescript
144
const myFont = localFont({
145
  src: './fonts/MyFont.woff2',
146
  declarations: [
147
    { prop: 'font-feature-settings', value: '"liga" 1' },
148
    { prop: 'font-variant', value: 'small-caps' }
149
  ]
150
});
151
```
152

153
## Usage Examples
154

155
### Basic Local Font
156

157
```typescript
158
import localFont from "@next/font/local";
159

160
const myFont = localFont({
161
  src: './fonts/MyFont-Regular.woff2',
162
  display: 'swap',
163
});
164

165
export default function App() {
166
  return (
167
    <div className={myFont.className}>
168
      <h1>Hello World</h1>
169
    </div>
170
  );
171
}
172
```
173

174
### Multiple Font Weights and Styles
175

176
```typescript
177
import localFont from "@next/font/local";
178

179
const myFontFamily = localFont({
180
  src: [
181
    {
182
      path: './fonts/MyFont-Light.woff2',
183
      weight: '300',
184
      style: 'normal',
185
    },
186
    {
187
      path: './fonts/MyFont-Regular.woff2', 
188
      weight: '400',
189
      style: 'normal',
190
    },
191
    {
192
      path: './fonts/MyFont-Bold.woff2',
193
      weight: '700', 
194
      style: 'normal',
195
    },
196
    {
197
      path: './fonts/MyFont-RegularItalic.woff2',
198
      weight: '400',
199
      style: 'italic',
200
    },
201
  ],
202
  display: 'swap',
203
});
204

205
export default function App() {
206
  return (
207
    <div className={myFontFamily.className}>
208
      <p style={{ fontWeight: 300 }}>Light text</p>
209
      <p style={{ fontWeight: 400 }}>Regular text</p>
210
      <p style={{ fontWeight: 700 }}>Bold text</p>
211
      <p style={{ fontWeight: 400, fontStyle: 'italic' }}>
212
        Italic text
213
      </p>
214
    </div>
215
  );
216
}
217
```
218

219
### Variable Font
220

221
```typescript
222
import localFont from "@next/font/local";
223

224
const myVariableFont = localFont({
225
  src: './fonts/MyVariableFont.woff2',
226
  display: 'swap',
227
  weight: '100 900', // Variable font weight range
228
  variable: '--font-my-variable',
229
});
230

231
export default function App() {
232
  return (
233
    <div className={`${myVariableFont.variable} font-sans`}>
234
      <h1 style={{ fontWeight: 150 }}>Very light</h1>
235
      <h2 style={{ fontWeight: 850 }}>Very bold</h2>
236
    </div>
237
  );
238
}
239
```
240

241
### With Fallback Optimization
242

243
```typescript
244
import localFont from "@next/font/local";
245

246
const myFont = localFont({
247
  src: './fonts/MyCustomSans.woff2',
248
  display: 'swap',
249
  adjustFontFallback: 'Arial',
250
  fallback: ['system-ui', 'arial'],
251
  preload: true,
252
});
253

254
export default function App() {
255
  return (
256
    <div className={myFont.className}>
257
      <h1>Optimized loading with minimal layout shift</h1>
258
    </div>
259
  );
260
}
261
```
262

263
### With CSS Custom Properties
264

265
```typescript
266
import localFont from "@next/font/local";
267

268
const headingFont = localFont({
269
  src: './fonts/MyHeading.woff2',
270
  variable: '--font-heading',
271
  display: 'swap',
272
});
273

274
const bodyFont = localFont({
275
  src: [
276
    {
277
      path: './fonts/MyBody-Regular.woff2',
278
      weight: '400',
279
      style: 'normal',
280
    },
281
    {
282
      path: './fonts/MyBody-Bold.woff2', 
283
      weight: '700',
284
      style: 'normal',
285
    },
286
  ],
287
  variable: '--font-body',
288
  display: 'swap',
289
});
290

291
// In your CSS or Tailwind config:
292
// .font-heading { font-family: var(--font-heading); }
293
// .font-body { font-family: var(--font-body); }
294

295
export default function App() {
296
  return (
297
    <div className={`${headingFont.variable} ${bodyFont.variable}`}>
298
      <h1 className="font-heading">Heading Text</h1>
299
      <p className="font-body">Body text with custom font</p>
300
    </div>
301
  );
302
}
303
```
304

305
### With Custom Font Features
306

307
```typescript
308
import localFont from "@next/font/local";
309

310
const myFont = localFont({
311
  src: './fonts/MyFont.woff2',
312
  display: 'swap',
313
  declarations: [
314
    { prop: 'font-feature-settings', value: '"liga" 1, "kern" 1' },
315
    { prop: 'font-variant-numeric', value: 'oldstyle-nums' },
316
  ],
317
});
318
```
319

320
## Supported Font Formats
321

322
Local fonts support common web font formats:
323

324
- **WOFF2** (recommended) - Best compression and wide browser support
325
- **WOFF** - Good fallback option
326
- **TTF/OTF** - Uncompressed formats, larger file sizes
327
- **EOT** - Legacy Internet Explorer support
328

329
## Best Practices
330

331
1. **Use WOFF2 format** for optimal file size and browser support
332
2. **Provide multiple weights/styles** in a single `localFont` call for better font family organization
333
3. **Enable preload** for above-the-fold fonts to improve loading performance
334
4. **Use adjustFontFallback** to minimize layout shift during font loading
335
5. **Specify appropriate display strategy** (`'swap'` is recommended for most cases)
336
6. **Use CSS custom properties** (`variable` option) for flexible styling with CSS-in-JS or Tailwind