0
# @next/font
1

2
@next/font provides built-in automatic self-hosting for web fonts with optimal loading performance and zero layout shift. It enables convenient use of Google Fonts and local font files with performance and privacy optimizations, automatically downloading CSS and font files at build time for self-hosting.
3

4
## Package Information
5

6
- **Package Name**: @next/font
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `pnpm add @next/font` (included with Next.js 13+)
10

11
## Core Imports
12

13
For Google Fonts:
14

15
```typescript
16
import { Inter, Roboto, Open_Sans } from "@next/font/google";
17
```
18

19
For Local Fonts:
20

21
```typescript
22
import localFont from "@next/font/local";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { Inter, Roboto } = require("@next/font/google");
29
const localFont = require("@next/font/local").default;
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { Inter } from "@next/font/google";
36
import localFont from "@next/font/local";
37

38
// Google Font
39
const inter = Inter({
40
  subsets: ["latin"],
41
  variable: "--font-inter",
42
});
43

44
// Local Font
45
const myFont = localFont({
46
  src: "./my-font.woff2",
47
  display: "swap",
48
});
49

50
// Use in JSX
51
export default function Page() {
52
  return (
53
    <div className={inter.className}>
54
      <h1 className={myFont.className}>Hello World</h1>
55
    </div>
56
  );
57
}
58
```
59

60
## Architecture
61

62
@next/font is built around several key components:
63

64
- **Google Fonts Integration**: 1625+ pre-configured Google Font functions with automatic optimization
65
- **Local Font Support**: Universal loader for custom font files with fallback generation
66
- **Build-time Processing**: Downloads and processes fonts during build for optimal performance
67
- **CSS Variable Support**: Optional CSS custom properties for variable fonts and theme switching
68
- **Fallback Generation**: Automatic fallback font metrics calculation to prevent layout shift
69
- **Self-hosting**: Downloads and serves all fonts from Next.js static assets
70

71
## Capabilities
72

73
### Google Fonts
74

75
Access to 1625+ Google Fonts with automatic optimization, self-hosting, and zero layout shift. Each font is available as a named export with TypeScript support and configurable options.
76

77
```typescript { .api }
78
// Generic Google Font function signature
79
function GoogleFont<T extends CssVariable | undefined = undefined>(options?: {
80
  weight?: string | string[] | 'variable';
81
  style?: string | string[];
82
  display?: Display;
83
  variable?: T;
84
  preload?: boolean;
85
  fallback?: string[];
86
  adjustFontFallback?: boolean;
87
  subsets?: string[];
88
}): T extends undefined ? NextFont : NextFontWithVariable;
89

90
type Display = 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
91
```
92

93
[Google Fonts](./google-fonts.md)
94

95
### Local Fonts
96

97
Universal font loader for custom font files with automatic fallback generation and optimal loading performance.
98

99
```typescript { .api }
100
function localFont<T extends CssVariable | undefined = undefined>(
101
  options: LocalFont<T>
102
): T extends undefined ? NextFont : NextFontWithVariable;
103

104
interface LocalFont<T extends CssVariable | undefined = undefined> {
105
  src: string | Array<{
106
    path: string;
107
    weight?: string;
108
    style?: string;
109
  }>;
110
  display?: Display;
111
  weight?: string;
112
  style?: string;
113
  adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
114
  fallback?: string[];
115
  preload?: boolean;
116
  variable?: T;
117
  declarations?: Array<{ prop: string; value: string }>;
118
}
119
```
120

121
[Local Fonts](./local-fonts.md)
122

123
## Core Types
124

125
```typescript { .api }
126
type CssVariable = `--${string}`;
127

128
type Display = 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
129

130
interface NextFont {
131
  className: string;
132
  style: { 
133
    fontFamily: string; 
134
    fontWeight?: number; 
135
    fontStyle?: string; 
136
  };
137
}
138

139
interface NextFontWithVariable extends NextFont {
140
  variable: string;
141
}
142
```
143

144
## Error Handling
145

146
@next/font throws `NextFontError` instances for configuration and loading issues. These errors are automatically caught and formatted by Next.js during development and build processes.
147

148
Common error scenarios include:
149
- Invalid font configuration options (invalid weight, style, or subset values)
150
- Network failures during font fetching in development mode
151
- Incompatible Next.js versions (requires Next.js 13+)
152
- Missing required font subsets or weights for specific Google Fonts
153
- Invalid local font file paths or unsupported font formats