0
# Font Family Styling
1
2
The FontFamily extension provides font family styling capabilities, allowing users to apply custom fonts to text selections with standard CSS font-family support.
3
4
## Capabilities
5
6
### FontFamily Extension
7
8
Extension for applying font families to text with CSS font-family property support.
9
10
```typescript { .api }
11
/**
12
* Extension for setting font family on specified node types
13
* Extends textStyle mark with fontFamily attribute
14
*/
15
const FontFamily: Extension<FontFamilyOptions>;
16
17
interface FontFamilyOptions {
18
/**
19
* Node types where font family can be applied
20
* @default ['textStyle']
21
* @example ['heading', 'paragraph', 'textStyle']
22
*/
23
types: string[];
24
}
25
```
26
27
**Usage Example:**
28
29
```typescript
30
import { Editor } from "@tiptap/core";
31
import { FontFamily } from "@tiptap/extension-text-style/font-family";
32
import { TextStyle } from "@tiptap/extension-text-style/text-style";
33
34
const editor = new Editor({
35
extensions: [
36
TextStyle, // Required dependency
37
FontFamily.configure({
38
types: ['textStyle', 'heading']
39
})
40
]
41
});
42
```
43
44
### Set Font Family Command
45
46
Apply a specific font family to the current text selection.
47
48
```typescript { .api }
49
/**
50
* Set the font family
51
* @param fontFamily - CSS font-family value (font name, font stack, or generic family)
52
* @returns Command result indicating success/failure
53
*/
54
setFontFamily(fontFamily: string): Command;
55
```
56
57
**Usage Examples:**
58
59
```typescript
60
// Single font names
61
editor.commands.setFontFamily("Arial");
62
editor.commands.setFontFamily("Times New Roman");
63
editor.commands.setFontFamily("Helvetica");
64
65
// Font stacks (fallback fonts)
66
editor.commands.setFontFamily("Arial, sans-serif");
67
editor.commands.setFontFamily("'Times New Roman', Times, serif");
68
editor.commands.setFontFamily("Georgia, 'Times New Roman', serif");
69
70
// Generic families
71
editor.commands.setFontFamily("serif");
72
editor.commands.setFontFamily("sans-serif");
73
editor.commands.setFontFamily("monospace");
74
75
// Web fonts
76
editor.commands.setFontFamily("'Open Sans', sans-serif");
77
editor.commands.setFontFamily("'Roboto Mono', monospace");
78
79
// Chain with other styling commands
80
editor.chain()
81
.setFontFamily("Georgia")
82
.setFontSize("18px")
83
.setColor("#333")
84
.run();
85
```
86
87
### Unset Font Family Command
88
89
Remove font family styling from the current text selection.
90
91
```typescript { .api }
92
/**
93
* Unset the font family, removing fontFamily attribute and cleaning up empty textStyle marks
94
* @returns Command result indicating success/failure
95
*/
96
unsetFontFamily(): Command;
97
```
98
99
**Usage Example:**
100
101
```typescript
102
// Remove font family and clean up empty styling
103
editor.commands.unsetFontFamily();
104
105
// Chain removal with other operations
106
editor.chain()
107
.unsetFontFamily()
108
.setColor("#000000")
109
.run();
110
```
111
112
## HTML Processing
113
114
### Font Family Parsing
115
116
The FontFamily extension includes straightforward HTML parsing:
117
118
- **Direct Style Reading**: Reads `font-family` value directly from `element.style.fontFamily`
119
- **CSS Format Support**: Supports all standard CSS font-family formats
120
- **Quote Preservation**: Maintains quotes around font names with spaces
121
- **Fallback Support**: Handles font stacks with multiple fallback fonts
122
123
### Rendering Output
124
125
- **CSS Format**: Renders as `style="font-family: {value}"` attribute
126
- **Clean Output**: Only adds font-family attribute when a value is present
127
- **Format Preservation**: Maintains exact font-family string including quotes and fallbacks
128
129
## Type System Integration
130
131
### Module Augmentation
132
133
The FontFamily extension augments TipTap's type system:
134
135
```typescript
136
// Extends core Commands interface
137
declare module '@tiptap/core' {
138
interface Commands<ReturnType> {
139
fontFamily: {
140
setFontFamily: (fontFamily: string) => ReturnType;
141
unsetFontFamily: () => ReturnType;
142
}
143
}
144
}
145
146
// Extends TextStyleAttributes interface
147
declare module '@tiptap/extension-text-style' {
148
interface TextStyleAttributes {
149
fontFamily?: string | null;
150
}
151
}
152
```
153
154
## Configuration Examples
155
156
### Basic Configuration
157
158
```typescript
159
import { FontFamily } from "@tiptap/extension-text-style/font-family";
160
161
const fontFamilyExtension = FontFamily.configure({
162
types: ['textStyle']
163
});
164
```
165
166
### Extended Node Type Support
167
168
```typescript
169
const fontFamilyExtension = FontFamily.configure({
170
types: ['textStyle', 'heading', 'paragraph']
171
});
172
```
173
174
This allows font families to be applied directly to headings and paragraphs in addition to inline text styling.
175
176
## Font Family Examples
177
178
### Common Font Combinations
179
180
```typescript
181
// System fonts
182
editor.commands.setFontFamily("-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif");
183
184
// Professional fonts
185
editor.commands.setFontFamily("'Times New Roman', Times, serif");
186
editor.commands.setFontFamily("Arial, Helvetica, sans-serif");
187
editor.commands.setFontFamily("Georgia, serif");
188
189
// Monospace fonts for code
190
editor.commands.setFontFamily("'Courier New', Courier, monospace");
191
editor.commands.setFontFamily("'Fira Code', 'Consolas', monospace");
192
193
// Google Fonts (assuming loaded)
194
editor.commands.setFontFamily("'Open Sans', sans-serif");
195
editor.commands.setFontFamily("'Roboto', sans-serif");
196
editor.commands.setFontFamily("'Playfair Display', serif");
197
```
198
199
### Integration with Font Loading
200
201
When using web fonts, ensure they are loaded before applying:
202
203
```typescript
204
// Check if font is loaded (if using Font Loading API)
205
document.fonts.ready.then(() => {
206
editor.commands.setFontFamily("'Custom Web Font', sans-serif");
207
});
208
```