0
# @next/font
1

2
@next/font is Next.js's official font optimization library that provides automatic self-hosting for any font file with zero layout shift. It enables optimal loading of web fonts with performance and privacy benefits by downloading CSS and font files at build time and self-hosting them with static assets, eliminating browser requests to Google.
3

4
## Package Information
5

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

11
## Core Imports
12

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

18
For Google Fonts:
19

20
```typescript
21
import { Poppins } from "@next/font/google";
22
```
23

24
For local fonts:
25

26
```typescript
27
import localFont from "@next/font/local";
28
```
29

30
## Basic Usage
31

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

36
// Google Font with optimal defaults
37
const inter = Inter({
38
  subsets: ["latin"],
39
  display: "swap",
40
});
41

42
// Local font with multiple files
43
const myFont = localFont({
44
  src: [
45
    {
46
      path: "./fonts/MyFont-Regular.woff2",
47
      weight: "400",
48
      style: "normal",
49
    },
50
    {
51
      path: "./fonts/MyFont-Bold.woff2", 
52
      weight: "700",
53
      style: "normal",
54
    },
55
  ],
56
  display: "swap",
57
});
58

59
// Usage in components
60
export default function App() {
61
  return (
62
    <div className={inter.className}>
63
      <h1 className={myFont.className}>Hello World</h1>
64
    </div>
65
  );
66
}
67
```
68

69
## Architecture
70

71
@next/font is built around several key components:
72

73
- **Google Fonts Integration**: 1569+ Google font families with type-safe function interfaces
74
- **Local Font Loading**: Support for self-hosted font files with multiple formats
75
- **Font Optimization**: Automatic self-hosting, subset optimization, and fallback generation
76
- **CSS Integration**: Zero layout shift using size-adjust property and calculated font metrics
77
- **TypeScript Support**: Complete type definitions with generic support for CSS custom properties
78
- **Build-time Processing**: Font downloading and optimization happens at build time, not runtime
79

80
## Capabilities
81

82
### Google Fonts
83

84
Access to Google Fonts library with automatic optimization and self-hosting. Each font family has a dedicated typed function with family-specific weight and subset options.
85

86
```typescript { .api }
87
// Example function signatures for Google fonts
88
function Inter<T extends CssVariable | undefined = undefined>(options?: {
89
  weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | 'variable' | Array<'100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'>;
90
  style?: 'normal' | Array<'normal'>;
91
  display?: Display;
92
  variable?: T;
93
  preload?: boolean;
94
  fallback?: string[];
95
  adjustFontFallback?: boolean;
96
  axes?: string[];
97
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'latin' | 'latin-ext' | 'vietnamese'>;
98
}): T extends undefined ? NextFont : NextFontWithVariable;
99

100
function Roboto<T extends CssVariable | undefined = undefined>(options: {
101
  weight: '100' | '300' | '400' | '500' | '700' | '900' | Array<'100' | '300' | '400' | '500' | '700' | '900'>;
102
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
103
  display?: Display;
104
  variable?: T;
105
  preload?: boolean;
106
  fallback?: string[];
107
  adjustFontFallback?: boolean;
108
  axes?: string[];
109
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'latin' | 'latin-ext' | 'vietnamese'>;
110
}): T extends undefined ? NextFont : NextFontWithVariable;
111
```
112

113
[Google Fonts](./google-fonts.md)
114

115
### Local Fonts
116

117
Support for loading local font files with comprehensive configuration options and automatic optimization.
118

119
```typescript { .api }
120
function localFont<T extends CssVariable | undefined = undefined>(
121
  options: LocalFont<T>
122
): T extends undefined ? NextFont : NextFontWithVariable;
123

124
interface LocalFont<T extends CssVariable | undefined = undefined> {
125
  src: string | Array<{
126
    path: string;
127
    weight?: string;
128
    style?: string;
129
  }>;
130
  display?: Display;
131
  weight?: string;
132
  style?: string;
133
  adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
134
  fallback?: string[];
135
  preload?: boolean;
136
  variable?: T;
137
  declarations?: Array<{ prop: string; value: string }>;
138
}
139
```
140

141
[Local Fonts](./local-fonts.md)
142

143
## Core Types
144

145
```typescript { .api }
146
interface NextFont {
147
  className: string;
148
  style: { 
149
    fontFamily: string; 
150
    fontWeight?: number; 
151
    fontStyle?: string;
152
  };
153
}
154

155
interface NextFontWithVariable extends NextFont {
156
  variable: string;
157
}
158

159
type CssVariable = `--${string}`;
160

161
type Display = 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
162
```
163

164
## Performance Features
165

166
- **Zero Layout Shift**: Uses CSS size-adjust property with calculated font metrics
167
- **Automatic Self-hosting**: Downloads and hosts fonts at build time
168
- **Subset Optimization**: Only includes required character subsets
169
- **Preloading**: Optional font preloading for critical fonts
170
- **Fallback Generation**: Automatically generates optimized fallback fonts
171
- **Variable Font Support**: Efficiently loads variable fonts when available