0
# Tiptap Typography Extension
1

2
The Typography extension for Tiptap provides automatic typography replacements for common text input patterns. It converts conventional text sequences into proper typographic characters, including em dashes, ellipsis, smart quotes, arrows, mathematical symbols, and fractions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Typography } from "@tiptap/extension-typography";
15

16
// Or import specific input rule functions
17
import { 
18
  Typography, 
19
  emDash, 
20
  ellipsis, 
21
  openDoubleQuote,
22
  type TypographyOptions 
23
} from "@tiptap/extension-typography";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const { Typography } = require("@tiptap/extension-typography");
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { Editor } from "@tiptap/core";
36
import { Typography } from "@tiptap/extension-typography";
37

38
// Basic usage with default options
39
const editor = new Editor({
40
  extensions: [
41
    Typography,
42
  ],
43
  content: '<p>Hello World!</p>',
44
});
45

46
// Custom configuration
47
const editor = new Editor({
48
  extensions: [
49
    Typography.configure({
50
      emDash: '—',        // Enable em dash (-- → —)
51
      ellipsis: '…',      // Enable ellipsis (... → …)
52
      copyright: false,   // Disable copyright symbol
53
      trademark: '™',     // Enable trademark symbol
54
    }),
55
  ],
56
  content: '<p>Hello World!</p>',
57
});
58
```
59

60
## Architecture
61

62
The Typography extension is built around several key components:
63

64
- **Text Input Rules**: Individual functions that create text replacement rules for specific patterns
65
- **Options Configuration**: Comprehensive configuration system allowing enable/disable and character customization
66
- **Extension Integration**: Seamless integration with Tiptap's extension system and ProseMirror's input rule system
67
- **Pattern Matching**: Regex-based pattern detection for automatic text replacement
68

69
## Capabilities
70

71
### Typography Extension
72

73
Main extension class that provides comprehensive typography replacements for text input patterns.
74

75
```typescript { .api }
76
/**
77
 * Typography extension for Tiptap that automatically converts common text input patterns 
78
 * into proper typographic characters
79
 */
80
declare const Typography: Extension<TypographyOptions>;
81
```
82

83
### Typography Options Configuration
84

85
Configuration interface for controlling which typography replacements are enabled and their replacement characters.
86

87
```typescript { .api }
88
interface TypographyOptions {
89
  /** The em dash character (-- → —). Set to false to disable. @default '—' */
90
  emDash: false | string;
91
  /** The ellipsis character (... → …). Set to false to disable. @default '…' */
92
  ellipsis: false | string;
93
  /** The open double quote character. Set to false to disable. @default '"' */
94
  openDoubleQuote: false | string;
95
  /** The close double quote character. Set to false to disable. @default '"' */
96
  closeDoubleQuote: false | string;
97
  /** The open single quote character. Set to false to disable. @default ''' */
98
  openSingleQuote: false | string;
99
  /** The close single quote character. Set to false to disable. @default ''' */
100
  closeSingleQuote: false | string;
101
  /** The left arrow character (<- → ←). Set to false to disable. @default '←' */
102
  leftArrow: false | string;
103
  /** The right arrow character (-> → →). Set to false to disable. @default '→' */
104
  rightArrow: false | string;
105
  /** The copyright character ((c) → ©). Set to false to disable. @default '©' */
106
  copyright: false | string;
107
  /** The trademark character ((tm) → ™). Set to false to disable. @default '™' */
108
  trademark: false | string;
109
  /** The servicemark character ((sm) → ℠). Set to false to disable. @default '℠' */
110
  servicemark: false | string;
111
  /** The registered trademark character ((r) → ®). Set to false to disable. @default '®' */
112
  registeredTrademark: false | string;
113
  /** The one half character (1/2 → ½). Set to false to disable. @default '½' */
114
  oneHalf: false | string;
115
  /** The plus minus character (+/- → ±). Set to false to disable. @default '±' */
116
  plusMinus: false | string;
117
  /** The not equal character (!= → ≠). Set to false to disable. @default '≠' */
118
  notEqual: false | string;
119
  /** The laquo character (<< → «). Set to false to disable. @default '«' */
120
  laquo: false | string;
121
  /** The raquo character (>> → »). Set to false to disable. @default '»' */
122
  raquo: false | string;
123
  /** The multiplication character (x or * → ×). Set to false to disable. @default '×' */
124
  multiplication: false | string;
125
  /** The superscript two character (^2 → ²). Set to false to disable. @default '²' */
126
  superscriptTwo: false | string;
127
  /** The superscript three character (^3 → ³). Set to false to disable. @default '³' */
128
  superscriptThree: false | string;
129
  /** The one quarter character (1/4 → ¼). Set to false to disable. @default '¼' */
130
  oneQuarter: false | string;
131
  /** The three quarters character (3/4 → ¾). Set to false to disable. @default '¾' */
132
  threeQuarters: false | string;
133
}
134
```
135

136
### Individual Text Input Rule Functions
137

138
Each typography replacement has a corresponding function that creates a text input rule for that specific pattern.
139

140
```typescript { .api }
141
/** Creates text input rule for em dash replacement (-- → —) */
142
function emDash(override?: string): InputRule;
143

144
/** Creates text input rule for ellipsis replacement (... → …) */
145
function ellipsis(override?: string): InputRule;
146

147
/** Creates text input rule for opening double quote replacement */
148
function openDoubleQuote(override?: string): InputRule;
149

150
/** Creates text input rule for closing double quote replacement */
151
function closeDoubleQuote(override?: string): InputRule;
152

153
/** Creates text input rule for opening single quote replacement */
154
function openSingleQuote(override?: string): InputRule;
155

156
/** Creates text input rule for closing single quote replacement */
157
function closeSingleQuote(override?: string): InputRule;
158

159
/** Creates text input rule for left arrow replacement (<- → ←) */
160
function leftArrow(override?: string): InputRule;
161

162
/** Creates text input rule for right arrow replacement (-> → →) */
163
function rightArrow(override?: string): InputRule;
164

165
/** Creates text input rule for copyright symbol replacement ((c) → ©) */
166
function copyright(override?: string): InputRule;
167

168
/** Creates text input rule for trademark symbol replacement ((tm) → ™) */
169
function trademark(override?: string): InputRule;
170

171
/** Creates text input rule for service mark symbol replacement ((sm) → ℠) */
172
function servicemark(override?: string): InputRule;
173

174
/** Creates text input rule for registered trademark replacement ((r) → ®) */
175
function registeredTrademark(override?: string): InputRule;
176

177
/** Creates text input rule for one half fraction replacement (1/2 → ½) */
178
function oneHalf(override?: string): InputRule;
179

180
/** Creates text input rule for plus minus symbol replacement (+/- → ±) */
181
function plusMinus(override?: string): InputRule;
182

183
/** Creates text input rule for not equal symbol replacement (!= → ≠) */
184
function notEqual(override?: string): InputRule;
185

186
/** Creates text input rule for left guillemet replacement (<< → «) */
187
function laquo(override?: string): InputRule;
188

189
/** Creates text input rule for right guillemet replacement (>> → ») */
190
function raquo(override?: string): InputRule;
191

192
/** Creates text input rule for multiplication symbol replacement (x or * → ×) */
193
function multiplication(override?: string): InputRule;
194

195
/** Creates text input rule for superscript two replacement (^2 → ²) */
196
function superscriptTwo(override?: string): InputRule;
197

198
/** Creates text input rule for superscript three replacement (^3 → ³) */
199
function superscriptThree(override?: string): InputRule;
200

201
/** Creates text input rule for one quarter fraction replacement (1/4 → ¼) */
202
function oneQuarter(override?: string): InputRule;
203

204
/** Creates text input rule for three quarters fraction replacement (3/4 → ¾) */
205
function threeQuarters(override?: string): InputRule;
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { Editor } from "@tiptap/core";
212
import { Extension } from "@tiptap/core";
213
import { emDash, ellipsis, copyright } from "@tiptap/extension-typography";
214

215
// Creating a custom extension with specific rules
216
const CustomTypography = Extension.create({
217
  name: 'customTypography',
218
  
219
  addInputRules() {
220
    return [
221
      emDash('—'),        // Enable em dash with default character
222
      ellipsis('…'),      // Enable ellipsis with default character
223
      copyright('©'),     // Enable copyright with default character
224
    ];
225
  },
226
});
227

228
// Using in editor
229
const editor = new Editor({
230
  extensions: [CustomTypography],
231
  content: '<p>Type -- for em dash, ... for ellipsis, (c) for copyright</p>',
232
});
233
```
234

235
**Text Pattern Examples:**
236

237
When typing in the editor, these patterns are automatically replaced:
238

239
- `--` → `—` (em dash)
240
- `...` → `…` (ellipsis)  
241
- `"text"` → `"text"` (smart quotes)
242
- `'text'` → `'text'` (smart single quotes)
243
- `<-` → `←` (left arrow)
244
- `->` → `→` (right arrow)
245
- `1/2 ` → `½` (one half fraction, requires trailing space)
246
- `1/4 ` → `¼` (one quarter fraction, requires trailing space)
247
- `3/4 ` → `¾` (three quarters fraction, requires trailing space)  
248
- `^2` → `²` (superscript two)
249
- `+/-` → `±` (plus minus)
250
- `!=` → `≠` (not equal)
251
- `<<` → `«` (left guillemet)
252
- `>>` → `»` (right guillemet)
253
- `2*3` or `2x3` → `2×3` (multiplication symbol with digits)
254
- `(c)` → `©` (copyright)
255
- `(tm)` → `™` (trademark)
256
- `(r)` → `®` (registered trademark)
257

258
## Types
259

260
```typescript { .api }
261
/**
262
 * Input rule class from @tiptap/core that handles text pattern matching and replacement
263
 */
264
declare class InputRule {
265
  find: InputRuleFinder;
266
  handler: (props: {
267
    state: EditorState;
268
    range: Range;
269
    match: ExtendedRegExpMatchArray;
270
    commands: SingleCommands;
271
    chain: () => ChainedCommands;
272
    can: () => CanCommands;
273
  }) => void | null;
274

275
  constructor(config: {
276
    find: InputRuleFinder;
277
    handler: (props: {
278
      state: EditorState;
279
      range: Range;
280
      match: ExtendedRegExpMatchArray;
281
      commands: SingleCommands;
282
      chain: () => ChainedCommands;
283
      can: () => CanCommands;
284
    }) => void | null;
285
  });
286
}
287

288
/**
289
 * Extension base class from @tiptap/core
290
 */
291
declare class Extension<Options = any, Storage = any> {
292
  static create<O = any, S = any>(config?: Partial<ExtensionConfig<O, S>>): Extension<O, S>;
293
  configure(options?: Partial<Options>): Extension<Options, Storage>;
294
}
295

296
/**
297
 * Input rule finder type - can be a RegExp or function
298
 */
299
type InputRuleFinder = RegExp | ((text: string) => InputRuleMatch | null);
300

301
type InputRuleMatch = {
302
  index: number;
303
  text: string;
304
  replaceWith?: string;
305
  match?: RegExpMatchArray;
306
  data?: Record<string, any>;
307
};
308

309
type ExtendedRegExpMatchArray = RegExpMatchArray & {
310
  data?: Record<string, any>;
311
};
312

313
type Range = {
314
  from: number;
315
  to: number;
316
};
317

318
type SingleCommands = any;
319
type ChainedCommands = any;
320
type CanCommands = any;
321
type EditorState = any;
322
type ExtensionConfig<O, S> = any;
323
```