0
# Google Fonts
1

2
Google Fonts integration providing access to 1569+ font families with automatic optimization, self-hosting, and zero layout shift. Each font family has a dedicated typed function with family-specific configuration options.
3

4
## Capabilities
5

6
### Font Family Functions
7

8
Each Google font family is available as a named export function with TypeScript support for all available weights, styles, and subsets.
9

10
```typescript { .api }
11
// Generic signature pattern for all Google font functions
12
function FontName<T extends CssVariable | undefined = undefined>(options?: {
13
  weight?: string | string[] | 'variable';
14
  style?: string | string[];
15
  display?: Display;
16
  variable?: T;
17
  preload?: boolean;
18
  fallback?: string[];
19
  adjustFontFallback?: boolean;
20
  subsets?: string[];
21
  axes?: string[];
22
}): T extends undefined ? NextFont : NextFontWithVariable;
23
```
24

25
### Popular Font Examples
26

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

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

52
function Open_Sans<T extends CssVariable | undefined = undefined>(options?: {
53
  weight?: '300' | '400' | '500' | '600' | '700' | '800' | 'variable' | Array<'300' | '400' | '500' | '600' | '700' | '800'>;
54
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
55
  display?: Display;
56
  variable?: T;
57
  preload?: boolean;
58
  fallback?: string[];
59
  adjustFontFallback?: boolean;
60
  axes?: string[];
61
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'hebrew' | 'latin' | 'latin-ext' | 'vietnamese'>;
62
}): T extends undefined ? NextFont : NextFontWithVariable;
63

64
function Poppins<T extends CssVariable | undefined = undefined>(options: {
65
  weight: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | Array<'100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'>;
66
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
67
  display?: Display;
68
  variable?: T;
69
  preload?: boolean;
70
  fallback?: string[];
71
  adjustFontFallback?: boolean;
72
  axes?: string[];
73
  subsets?: Array<'devanagari' | 'latin' | 'latin-ext'>;
74
}): T extends undefined ? NextFont : NextFontWithVariable;
75

76
function Lato<T extends CssVariable | undefined = undefined>(options: {
77
  weight: '100' | '300' | '400' | '700' | '900' | Array<string>;
78
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
79
  display?: Display;
80
  variable?: T;
81
  preload?: boolean;
82
  fallback?: string[];
83
  adjustFontFallback?: boolean;
84
  axes?: string[];
85
  subsets?: Array<'latin' | 'latin-ext'>;
86
}): T extends undefined ? NextFont : NextFontWithVariable;
87
```
88

89
### Variable Font Support
90

91
Many Google fonts support variable font features with the `'variable'` weight option and `axes` configuration.
92

93
```typescript { .api }
94
function AR_One_Sans<T extends CssVariable | undefined = undefined>(options?: {
95
  weight?: '400' | '500' | '600' | '700' | 'variable' | Array<string>;
96
  style?: 'normal' | Array<'normal'>;
97
  display?: Display;
98
  variable?: T;
99
  preload?: boolean;
100
  fallback?: string[];
101
  adjustFontFallback?: boolean;
102
  subsets?: Array<'latin' | 'latin-ext' | 'vietnamese'>;
103
  axes?: 'ARRR'[];
104
}): T extends undefined ? NextFont : NextFontWithVariable;
105
```
106

107
## Configuration Options
108

109
### weight
110
**Type**: `string | string[] | 'variable'`  
111
**Description**: Font weight(s) to load. Use `'variable'` for variable fonts or array for multiple weights.
112

113
**Usage Examples:**
114
```typescript
115
// Single weight
116
const inter = Inter({ weight: '400' });
117

118
// Multiple weights  
119
const roboto = Roboto({ weight: ['400', '700'] });
120

121
// Variable font
122
const inter = Inter({ weight: 'variable' });
123
```
124

125
### style
126
**Type**: `string | string[]`  
127
**Description**: Font style(s) to load. Typically `'normal'` or `'italic'`.
128

129
**Usage Examples:**
130
```typescript
131
// Normal style only
132
const inter = Inter({ style: 'normal' });
133

134
// Both normal and italic
135
const roboto = Roboto({ style: ['normal', 'italic'] });
136
```
137

138
### display
139
**Type**: `Display`  
140
**Description**: CSS font-display strategy for loading behavior.
141

142
**Values**: `'auto' | 'block' | 'swap' | 'fallback' | 'optional'`
143

144
### variable
145
**Type**: `` `--${string}` | undefined``  
146
**Description**: CSS custom property name for the font family. When provided, returns `NextFontWithVariable`.
147

148
**Usage Examples:**
149
```typescript
150
const inter = Inter({ variable: '--font-inter' });
151
// inter.variable === '--font-inter'
152
// inter.className includes the CSS custom property
153
```
154

155
### preload
156
**Type**: `boolean`  
157
**Description**: Whether to preload the font file. Recommended for above-the-fold content.
158

159
### fallback
160
**Type**: `string[]`  
161
**Description**: Fallback font stack for the font family.
162

163
**Usage Examples:**
164
```typescript
165
const inter = Inter({ 
166
  fallback: ['system-ui', 'arial'] 
167
});
168
```
169

170
### adjustFontFallback
171
**Type**: `boolean`  
172
**Description**: Automatically adjust fallback font metrics to match the web font, reducing layout shift.
173

174
### subsets
175
**Type**: `string[]`  
176
**Description**: Font subsets to include. Reduces file size by only including needed characters.
177

178
**Common Subsets:**
179
- `'latin'` - Basic Latin characters
180
- `'latin-ext'` - Extended Latin characters  
181
- `'cyrillic'` - Cyrillic characters
182
- `'greek'` - Greek characters
183
- `'vietnamese'` - Vietnamese characters
184

185
### axes
186
**Type**: `string[]`  
187
**Description**: Variable font axes to include (for variable fonts only). Specifies which variable font axes to use when loading variable fonts.
188

189
**Usage Examples:**
190
```typescript
191
// Variable font with specific axes
192
const interVariable = Inter({
193
  weight: 'variable',
194
  axes: ['slnt', 'wght'] // Only load slant and weight axes
195
});
196
```
197

198
## Usage Examples
199

200
```typescript
201
import { Inter, Roboto, Poppins } from "@next/font/google";
202

203
// Basic usage with optimal defaults
204
const inter = Inter({
205
  subsets: ['latin'],
206
  display: 'swap',
207
});
208

209
// Multiple weights and styles
210
const roboto = Roboto({
211
  weight: ['400', '700'],
212
  style: ['normal', 'italic'],
213
  subsets: ['latin', 'latin-ext'],
214
  display: 'swap',
215
});
216

217
// Variable font with CSS custom property
218
const poppins = Poppins({
219
  weight: 'variable',
220
  subsets: ['latin'],
221
  variable: '--font-poppins',
222
  display: 'swap',
223
});
224

225
// With custom fallbacks and preload
226
const headingFont = Inter({
227
  weight: ['600', '700'],
228
  subsets: ['latin'],
229
  display: 'swap',
230
  preload: true,
231
  fallback: ['system-ui', 'arial'],
232
  adjustFontFallback: true,
233
});
234

235
// Component usage
236
export default function MyApp() {
237
  return (
238
    <div className={inter.className}>
239
      <h1 className={`${poppins.variable} font-sans`}>
240
        Using CSS Custom Property
241
      </h1>
242
      <p style={roboto.style}>
243
        Using inline styles
244
      </p>
245
    </div>
246
  );
247
}
248
```
249

250
## Available Font Families
251

252
The package includes 1569 Google font families. Each font family has its own typed function with family-specific options for weights, styles, and subsets. Some popular families include:
253

254
- **Sans-serif**: Inter, Roboto, Open_Sans, Poppins, Lato, Montserrat, Source_Sans_Pro, Nunito Sans, Ubuntu, Raleway
255
- **Serif**: Merriweather, Playfair_Display, Lora, Source_Serif_Pro, Crimson_Text, Libre_Baskerville
256
- **Monospace**: Roboto_Mono, Source_Code_Pro, JetBrains_Mono, Fira_Code, Ubuntu_Mono
257
- **Display**: Oswald, Bebas_Neue, Abril_Fatface, Righteous, Fredoka_One
258

259
Font names in imports use underscore notation (e.g., `Open_Sans` for "Open Sans", `JetBrains_Mono` for "JetBrains Mono").