0
# Google Fonts
1

2
Google Fonts integration providing access to 1625+ Google Font families with automatic optimization, self-hosting, and zero layout shift. Each font is available as a named export with full TypeScript support.
3

4
## Capabilities
5

6
### Font Functions
7

8
Every Google Font is available as a named export function. Font names are transformed from their Google Fonts names by replacing spaces and special characters with underscores.
9

10
```typescript { .api }
11
/**
12
 * Generic Google Font function signature
13
 * @param options - Font configuration options
14
 * @returns Font object with className, style, and optional variable property
15
 */
16
function GoogleFont<T extends CssVariable | undefined = undefined>(options?: {
17
  weight?: string | string[] | 'variable';
18
  style?: string | string[];
19
  display?: Display;
20
  variable?: T;
21
  preload?: boolean;
22
  fallback?: string[];
23
  adjustFontFallback?: boolean;
24
  subsets?: string[];
25
}): T extends undefined ? NextFont : NextFontWithVariable;
26
```
27

28
**Popular Font Examples:**
29

30
```typescript { .api }
31
// Inter - Variable font
32
function Inter<T extends CssVariable | undefined = undefined>(options?: {
33
  weight?: 'variable' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | Array<'100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'>;
34
  style?: 'normal' | Array<'normal'>;
35
  display?: Display;
36
  variable?: T;
37
  preload?: boolean;
38
  fallback?: string[];
39
  adjustFontFallback?: boolean;
40
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'latin' | 'latin-ext' | 'vietnamese'>;
41
}): T extends undefined ? NextFont : NextFontWithVariable;
42

43
// Roboto - Standard weights
44
function Roboto<T extends CssVariable | undefined = undefined>(options: {
45
  weight: '100' | '300' | '400' | '500' | '700' | '900' | Array<'100' | '300' | '400' | '500' | '700' | '900'>;
46
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
47
  display?: Display;
48
  variable?: T;
49
  preload?: boolean;
50
  fallback?: string[];
51
  adjustFontFallback?: boolean;
52
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'latin' | 'latin-ext' | 'vietnamese'>;
53
}): T extends undefined ? NextFont : NextFontWithVariable;
54

55
// Open_Sans - Variable font with named instance weights
56
function Open_Sans<T extends CssVariable | undefined = undefined>(options?: {
57
  weight?: 'variable' | '300' | '400' | '500' | '600' | '700' | '800' | Array<'300' | '400' | '500' | '600' | '700' | '800'>;
58
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
59
  display?: Display;
60
  variable?: T;
61
  preload?: boolean;
62
  fallback?: string[];
63
  adjustFontFallback?: boolean;
64
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'hebrew' | 'latin' | 'latin-ext' | 'math' | 'symbols' | 'vietnamese'>;
65
}): T extends undefined ? NextFont : NextFontWithVariable;
66
```
67

68
### Font Options
69

70
#### Weight Configuration
71

72
```typescript { .api }
73
weight?: string | string[] | 'variable';
74
```
75

76
- **Single weight**: `'400'`, `'700'` - Loads specific font weight
77
- **Multiple weights**: `['400', '700']` - Loads multiple weights
78
- **Variable fonts**: `'variable'` - Loads the variable font version if available
79
- **Required for some fonts**: Fonts like Roboto require explicit weight specification
80

81
#### Style Configuration
82

83
```typescript { .api }
84
style?: string | string[];
85
```
86

87
- **Single style**: `'normal'`, `'italic'` - Loads specific font style
88
- **Multiple styles**: `['normal', 'italic']` - Loads multiple styles
89
- **Default**: Most fonts default to `'normal'` if not specified
90

91
#### Display Configuration
92

93
```typescript { .api }
94
display?: Display;
95
```
96

97
Controls the CSS `font-display` property:
98
- **'auto'**: Browser default behavior
99
- **'block'**: Block rendering until font loads
100
- **'swap'**: Use fallback immediately, swap when font loads (recommended)
101
- **'fallback'**: Brief block period, then use fallback
102
- **'optional'**: Use fallback if font doesn't load quickly
103

104
#### Variable Fonts
105

106
```typescript { .api }
107
variable?: T;
108
```
109

110
Creates a CSS custom property for the font family:
111

112
```typescript
113
const inter = Inter({
114
  subsets: ['latin'],
115
  variable: '--font-inter',
116
});
117

118
// Usage in CSS
119
// font-family: var(--font-inter);
120
```
121

122
#### Preloading
123

124
```typescript { .api }
125
preload?: boolean;
126
```
127

128
Controls whether font files are preloaded:
129
- **true**: Adds `<link rel="preload">` for faster font loading
130
- **false**: No preloading (default for non-critical fonts)
131

132
#### Subsets
133

134
```typescript { .api }
135
subsets?: string[];
136
```
137

138
Specifies which font subsets to load. Common subsets include:
139
- **'latin'**: Basic Latin characters (most common)
140
- **'latin-ext'**: Extended Latin characters
141
- **'cyrillic'**: Cyrillic script
142
- **'greek'**: Greek script
143
- **'vietnamese'**: Vietnamese characters
144

145
#### Fallback Fonts
146

147
```typescript { .api }
148
fallback?: string[];
149
adjustFontFallback?: boolean;
150
```
151

152
- **fallback**: Array of fallback font names
153
- **adjustFontFallback**: Automatically calculate fallback font metrics to prevent layout shift
154

155
## Usage Examples
156

157
### Basic Google Font
158

159
```typescript
160
import { Inter } from "@next/font/google";
161

162
const inter = Inter({
163
  subsets: ['latin'],
164
});
165

166
export default function Page() {
167
  return (
168
    <div className={inter.className}>
169
      <p>This text uses Inter font</p>
170
    </div>
171
  );
172
}
173
```
174

175
### Variable Font with CSS Variable
176

177
```typescript
178
import { Inter } from "@next/font/google";
179

180
const inter = Inter({
181
  subsets: ['latin'],
182
  variable: '--font-inter',
183
});
184

185
export default function RootLayout({ children }) {
186
  return (
187
    <html lang="en" className={inter.variable}>
188
      <body>{children}</body>
189
    </html>
190
  );
191
}
192
```
193

194
### Multiple Weights and Styles
195

196
```typescript
197
import { Roboto } from "@next/font/google";
198

199
const roboto = Roboto({
200
  weight: ['300', '400', '700'],
201
  style: ['normal', 'italic'],
202
  subsets: ['latin'],
203
  display: 'swap',
204
});
205
```
206

207
### Custom Fallbacks
208

209
```typescript
210
import { Playfair_Display } from "@next/font/google";
211

212
const playfair = Playfair_Display({
213
  weight: ['400', '700'],
214
  subsets: ['latin'],
215
  fallback: ['Georgia', 'serif'],
216
  adjustFontFallback: true,
217
});
218
```
219

220
### Preloading Critical Fonts
221

222
```typescript
223
import { Inter } from "@next/font/google";
224

225
const inter = Inter({
226
  subsets: ['latin'],
227
  preload: true, // Preload for above-the-fold content
228
});
229
```
230

231
## Font Name Transformations
232

233
Google Font names are transformed for JavaScript compatibility:
234

235
- **Spaces to underscores**: "Open Sans" → `Open_Sans`
236
- **Hyphens to underscores**: "Source Sans Pro" → `Source_Sans_Pro` 
237
- **Special characters removed**: "Josefin Sans" → `Josefin_Sans`
238
- **Numbers preserved**: "Roboto Mono" → `Roboto_Mono`
239

240
## Available Fonts
241

242
The package includes 1625+ Google Fonts. Some popular examples:
243

244
### Sans-serif Fonts
245
- `Inter` - Modern variable font, excellent for UI
246
- `Roboto` - Google's signature font
247
- `Open_Sans` - Friendly, readable font
248
- `Lato` - Humanist sans-serif
249
- `Montserrat` - Geometric sans-serif
250

251
### Serif Fonts  
252
- `Playfair_Display` - High-contrast serif
253
- `Merriweather` - Designed for screens
254
- `Lora` - Brush-style serif
255
- `Source_Serif_Pro` - Adobe's serif font
256

257
### Monospace Fonts
258
- `Fira_Code` - With programming ligatures
259
- `Source_Code_Pro` - Adobe's monospace font
260
- `JetBrains_Mono` - Designed for developers
261
- `Roboto_Mono` - Google's monospace font
262

263
### Display Fonts
264
- `Oswald` - Gothic-style display font
265
- `Bebas_Neue` - Condensed display font
266
- `Righteous` - Casual display font
267

268
## Performance Considerations
269

270
- **Subset selection**: Only include necessary language subsets
271
- **Weight optimization**: Load only required font weights
272
- **Variable fonts**: Use variable fonts when available for better performance
273
- **Preloading**: Preload fonts used above the fold
274
- **Fallback adjustment**: Enable automatic fallback metrics for better user experience