0
# Font Family Extension
1

2
Font Family Extension is a Tiptap editor extension that enables users to apply custom font families to selected text within Tiptap editor instances. It extends Tiptap's core functionality by integrating with the text-style extension to provide seamless font family styling capabilities.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-font-family
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-font-family @tiptap/extension-text-style`
10

11
## Core Imports
12

13
```typescript
14
import { FontFamily } from "@tiptap/extension-font-family";
15
import FontFamily from "@tiptap/extension-font-family"; // default import
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { FontFamily } = require("@tiptap/extension-font-family");
22
```
23

24
Import types:
25

26
```typescript
27
import { FontFamilyOptions } from "@tiptap/extension-font-family";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Editor } from "@tiptap/core";
34
import StarterKit from "@tiptap/starter-kit";
35
import { FontFamily } from "@tiptap/extension-font-family";
36
import { TextStyle } from "@tiptap/extension-text-style";
37

38
// Create editor with FontFamily extension
39
const editor = new Editor({
40
  element: document.querySelector('#editor'),
41
  extensions: [
42
    StarterKit,
43
    TextStyle, // Required dependency
44
    FontFamily.configure({
45
      types: ['textStyle'], // Default configuration
46
    }),
47
  ],
48
});
49

50
// Set font family for selected text
51
editor.commands.setFontFamily('Arial, sans-serif');
52
editor.commands.setFontFamily('Georgia, serif');
53

54
// Remove font family from selected text
55
editor.commands.unsetFontFamily();
56
```
57

58
## Capabilities
59

60
### FontFamily Extension
61

62
Main extension class that provides font family functionality to Tiptap editor.
63

64
```typescript { .api }
65
/**
66
 * FontFamily extension for Tiptap editor
67
 * Provides commands to set and unset font family on selected text
68
 */
69
declare const FontFamily: Extension<FontFamilyOptions>;
70

71
export default FontFamily;
72
export { FontFamily };
73
```
74

75
### Configuration Options
76

77
Extension configuration interface defining which node types support font family styling.
78

79
```typescript { .api }
80
export interface FontFamilyOptions {
81
  /**
82
   * A list of node names where the font family can be applied.
83
   * @default ['textStyle']
84
   * @example ['heading', 'paragraph']
85
   */
86
  types: string[]
87
}
88
```
89

90
### Editor Commands
91

92
The extension adds font family commands to the Tiptap editor instance.
93

94
#### Set Font Family Command
95

96
Sets font family on selected text or at current cursor position.
97

98
```typescript { .api }
99
/**
100
 * Set the font family for selected text
101
 * @param fontFamily The font family value (CSS font-family format)
102
 * @returns Command execution result
103
 * @example editor.commands.setFontFamily('Arial, sans-serif')
104
 * @example editor.commands.setFontFamily('Georgia, "Times New Roman", serif')
105
 */
106
editor.commands.setFontFamily(fontFamily: string): boolean;
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
// Set single font family
113
editor.commands.setFontFamily('Arial');
114

115
// Set font family with fallbacks
116
editor.commands.setFontFamily('Helvetica, Arial, sans-serif');
117

118
// Set font family with quoted names for fonts with spaces
119
editor.commands.setFontFamily('"Times New Roman", Times, serif');
120

121
// Set web font
122
editor.commands.setFontFamily('"Open Sans", sans-serif');
123
```
124

125
#### Unset Font Family Command
126

127
Removes font family styling from selected text.
128

129
```typescript { .api }
130
/**
131
 * Remove font family styling from selected text
132
 * @returns Command execution result
133
 * @example editor.commands.unsetFontFamily()
134
 */
135
editor.commands.unsetFontFamily(): boolean;
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
// Remove font family from current selection
142
editor.commands.unsetFontFamily();
143

144
// Chain with other commands
145
editor.commands.selectAll().unsetFontFamily();
146
```
147

148
## Text Style Integration
149

150
This extension requires and integrates with `@tiptap/extension-text-style` to function properly.
151

152
### Global Attributes
153

154
The extension adds font family support to configured node types:
155

156
```typescript { .api }
157
interface TextStyleAttributes {
158
  fontFamily?: string | null;
159
}
160
```
161

162
### HTML Parsing and Rendering
163

164
The extension automatically handles HTML conversion:
165

166
- **HTML → Editor**: Parses `style="font-family: ..."` attributes from HTML elements
167
- **Editor → HTML**: Renders font family as inline CSS style attributes
168

169
**HTML Example:**
170

171
```html
172
<!-- Input HTML -->
173
<p>This text has <span style="font-family: Arial, sans-serif">custom font family</span>.</p>
174

175
<!-- Editor automatically parses the font-family style -->
176
<!-- Output HTML maintains the same format -->
177
```
178

179
## Type Definitions
180

181
Complete TypeScript definitions for all exported types:
182

183
```typescript { .api }
184
/**
185
 * Configuration options for FontFamily extension
186
 */
187
export interface FontFamilyOptions {
188
  types: string[];
189
}
190

191
/**
192
 * Extension class type
193
 */
194
export declare const FontFamily: Extension<FontFamilyOptions>;
195

196
/**
197
 * Module augmentation for editor commands
198
 */
199
declare module '@tiptap/core' {
200
  interface Commands<ReturnType> {
201
    fontFamily: {
202
      setFontFamily: (fontFamily: string) => ReturnType;
203
      unsetFontFamily: () => ReturnType;
204
    }
205
  }
206
}
207

208
/**
209
 * Module augmentation for text style attributes
210
 */
211
declare module '@tiptap/extension-text-style' {
212
  interface TextStyleAttributes {
213
    fontFamily?: string | null;
214
  }
215
}
216
```
217

218
## Installation Requirements
219

220
This extension has peer dependencies that must be installed:
221

222
```bash
223
npm install @tiptap/extension-font-family @tiptap/extension-text-style
224
```
225

226
The `@tiptap/extension-text-style` package must be included in your editor extensions array for FontFamily to work properly.