0
# Tiptap Starter Kit
1
2
The Tiptap Starter Kit provides a comprehensive collection of essential editor extensions bundled together for quick setup of rich-text editing functionality. It's built on top of the headless Tiptap editor framework and includes 20+ commonly needed extensions like text formatting, document structure, lists, links, and editor utilities.
3
4
## Package Information
5
6
- **Package Name**: @tiptap/starter-kit
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/starter-kit`
10
11
## Core Imports
12
13
```typescript
14
import { StarterKit } from "@tiptap/starter-kit";
15
import type { StarterKitOptions } from "@tiptap/starter-kit";
16
```
17
18
Default import:
19
20
```typescript
21
import StarterKit from "@tiptap/starter-kit";
22
```
23
24
CommonJS:
25
26
```javascript
27
const { StarterKit } = require("@tiptap/starter-kit");
28
```
29
30
## Basic Usage
31
32
```typescript
33
import { Editor } from "@tiptap/core";
34
import StarterKit from "@tiptap/starter-kit";
35
36
// Use with default configuration (all extensions enabled)
37
const editor = new Editor({
38
element: document.querySelector("#editor"),
39
extensions: [StarterKit],
40
content: "<p>Hello World!</p>",
41
});
42
43
// Use with selective configuration
44
const customEditor = new Editor({
45
element: document.querySelector("#editor"),
46
extensions: [
47
StarterKit.configure({
48
// Disable some extensions
49
bold: false,
50
italic: false,
51
// Configure others
52
heading: {
53
levels: [1, 2, 3],
54
},
55
link: {
56
openOnClick: false,
57
HTMLAttributes: {
58
class: "custom-link",
59
},
60
},
61
}),
62
],
63
content: "<h1>Custom Editor</h1><p>With selective extensions.</p>",
64
});
65
```
66
67
## Capabilities
68
69
### StarterKit Extension
70
71
Creates a bundled extension containing 20+ essential Tiptap extensions for rich-text editing. Each bundled extension can be individually configured or disabled.
72
73
```typescript { .api }
74
const StarterKit: Extension<StarterKitOptions>;
75
```
76
77
**Usage Examples:**
78
79
```typescript
80
// Use with default configuration (all extensions enabled)
81
const editor = new Editor({
82
extensions: [StarterKit],
83
});
84
85
// Configure specific extensions
86
const editor = new Editor({
87
extensions: [
88
StarterKit.configure({
89
bold: false, // Disable bold
90
heading: { levels: [1, 2, 3] }, // Configure heading levels
91
link: { openOnClick: true }, // Configure link behavior
92
}),
93
],
94
});
95
96
// Extend with additional functionality
97
const customExtension = StarterKit.extend({
98
name: 'customStarterKit',
99
addCommands() {
100
return {
101
customCommand: () => ({ commands }) => {
102
// Custom command implementation
103
return true;
104
},
105
};
106
},
107
});
108
```
109
110
## Configuration Options
111
112
### StarterKitOptions Interface
113
114
Configuration interface for enabling/disabling and customizing bundled extensions.
115
116
```typescript { .api }
117
interface StarterKitOptions {
118
// Text formatting extensions
119
bold: Partial<BoldOptions> | false;
120
italic: Partial<ItalicOptions> | false;
121
underline: Partial<UnderlineOptions> | false;
122
strike: Partial<StrikeOptions> | false;
123
code: Partial<CodeOptions> | false;
124
125
// Document structure extensions
126
document: false;
127
paragraph: Partial<ParagraphOptions> | false;
128
heading: Partial<HeadingOptions> | false;
129
blockquote: Partial<BlockquoteOptions> | false;
130
horizontalRule: Partial<HorizontalRuleOptions> | false;
131
hardBreak: Partial<HardBreakOptions> | false;
132
text: false;
133
134
// List extensions
135
bulletList: Partial<BulletListOptions> | false;
136
orderedList: Partial<OrderedListOptions> | false;
137
listItem: Partial<ListItemOptions> | false;
138
listKeymap: Partial<ListKeymapOptions> | false;
139
140
// Code extensions
141
codeBlock: Partial<CodeBlockOptions> | false;
142
143
// Link extensions
144
link: Partial<LinkOptions> | false;
145
146
// Editor utilities
147
undoRedo: Partial<UndoRedoOptions> | false;
148
dropcursor: Partial<DropcursorOptions> | false;
149
gapcursor: false;
150
trailingNode: Partial<TrailingNodeOptions> | false;
151
}
152
```
153
154
**Configuration Examples:**
155
156
```typescript
157
// Disable specific extensions
158
const minimalConfig: Partial<StarterKitOptions> = {
159
bold: false,
160
italic: false,
161
underline: false,
162
strike: false,
163
};
164
165
// Configure extension options
166
const customConfig: Partial<StarterKitOptions> = {
167
heading: {
168
levels: [1, 2, 3, 4], // Only allow h1-h4
169
},
170
link: {
171
openOnClick: false,
172
HTMLAttributes: {
173
class: "editor-link",
174
rel: "nofollow",
175
},
176
},
177
codeBlock: {
178
HTMLAttributes: {
179
class: "code-block",
180
},
181
},
182
};
183
184
// Mix of disabled and configured extensions
185
const hybridConfig: Partial<StarterKitOptions> = {
186
// Disable some extensions
187
underline: false,
188
horizontalRule: false,
189
dropcursor: false,
190
191
// Configure others
192
blockquote: {
193
HTMLAttributes: {
194
class: "custom-blockquote",
195
},
196
},
197
bulletList: {
198
HTMLAttributes: {
199
class: "bullet-list",
200
},
201
},
202
};
203
```
204
205
## Bundled Extensions
206
207
The StarterKit includes the following extensions:
208
209
### Text Formatting
210
- **Bold**: Bold text formatting (`**text**` or Ctrl+B)
211
- **Italic**: Italic text formatting (`*text*` or Ctrl+I)
212
- **Underline**: Underline text formatting (Ctrl+U)
213
- **Strike**: Strikethrough formatting (`~~text~~`)
214
- **Code**: Inline code formatting (`` `code` ``)
215
216
### Document Structure
217
- **Document**: Root document node (required)
218
- **Paragraph**: Paragraph blocks (default block type)
219
- **Heading**: Heading levels (h1-h6) with `#` syntax support
220
- **Blockquote**: Blockquote formatting (`>` syntax)
221
- **Horizontal Rule**: Horizontal dividers (`---` syntax)
222
- **Hard Break**: Line breaks (Shift+Enter)
223
- **Text**: Text nodes (required)
224
225
### Lists
226
- **Bullet List**: Bullet point lists (`-` or `*` syntax)
227
- **Ordered List**: Numbered lists (`1.` syntax)
228
- **List Item**: List item behavior and nesting
229
- **List Keymap**: Keyboard shortcuts for list operations
230
231
### Code
232
- **Code Block**: Multi-line code blocks with syntax highlighting support
233
234
### Links
235
- **Link**: Link functionality with automatic detection and custom attributes
236
237
### Editor Utilities
238
- **Undo Redo**: Undo/redo functionality (Ctrl+Z/Ctrl+Y)
239
- **Drop Cursor**: Visual cursor indicator during drag operations
240
- **Gap Cursor**: Cursor positioning in empty areas between blocks
241
- **Trailing Node**: Ensures editor always ends with a paragraph
242
243
## Types
244
245
### Core Extension Types
246
247
```typescript { .api }
248
// Core extension from @tiptap/core
249
interface Extension<Options = any, Storage = any> {
250
configure(options?: Partial<Options>): Extension<Options, Storage>;
251
extend<ExtendedOptions = Options, ExtendedStorage = Storage>(
252
extendedConfig?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
253
): Extension<ExtendedOptions, ExtendedStorage>;
254
}
255
256
// Base extension types (imported from respective extension packages)
257
interface BoldOptions {
258
/**
259
* HTML attributes to add to the bold element.
260
* @default {}
261
*/
262
HTMLAttributes: Record<string, any>;
263
}
264
265
interface ItalicOptions {
266
/**
267
* HTML attributes to add to the italic element.
268
* @default {}
269
*/
270
HTMLAttributes: Record<string, any>;
271
}
272
273
interface HeadingOptions {
274
/**
275
* The available heading levels.
276
* @default [1, 2, 3, 4, 5, 6]
277
*/
278
levels: number[];
279
280
/**
281
* The HTML attributes for a heading node.
282
* @default {}
283
*/
284
HTMLAttributes: Record<string, any>;
285
}
286
287
interface LinkOptions {
288
/**
289
* If enabled, the extension will automatically add links as you type.
290
* @default true
291
*/
292
autolink: boolean;
293
294
/**
295
* An array of custom protocols to be registered with linkifyjs.
296
* @default []
297
*/
298
protocols: Array<LinkProtocolOptions | string>;
299
300
/**
301
* Default protocol to use when no protocol is specified.
302
* @default 'http'
303
*/
304
defaultProtocol: string;
305
306
/**
307
* If enabled, links will be opened on click.
308
* @default true
309
*/
310
openOnClick: boolean;
311
312
/**
313
* If enabled, the link will be selected when clicked.
314
* @default false
315
*/
316
enableClickSelection: boolean;
317
318
/**
319
* Adds a link to the current selection if the pasted content only contains an url.
320
* @default true
321
*/
322
linkOnPaste: boolean;
323
324
/**
325
* HTML attributes to add to the link element.
326
* @default {}
327
*/
328
HTMLAttributes: Record<string, any>;
329
330
/**
331
* @deprecated Use the `shouldAutoLink` option instead.
332
* A validation function that modifies link verification for the auto linker.
333
*/
334
validate: (url: string) => boolean;
335
336
/**
337
* A validation function which is used for configuring link verification for preventing XSS attacks.
338
* Only modify this if you know what you're doing.
339
*/
340
isAllowedUri: (
341
url: string,
342
ctx: {
343
defaultValidate: (url: string) => boolean;
344
protocols: Array<LinkProtocolOptions | string>;
345
defaultProtocol: string;
346
}
347
) => boolean;
348
349
/**
350
* Determines whether a valid link should be automatically linked in the content.
351
*/
352
shouldAutoLink: (url: string) => boolean;
353
}
354
355
interface CodeBlockOptions {
356
/**
357
* Adds a prefix to language classes that are applied to code tags.
358
* @default 'language-'
359
*/
360
languageClassPrefix: string;
361
362
/**
363
* Define whether the node should be exited on triple enter.
364
* @default true
365
*/
366
exitOnTripleEnter: boolean;
367
368
/**
369
* Define whether the node should be exited on arrow down if there is no node after it.
370
* @default true
371
*/
372
exitOnArrowDown: boolean;
373
374
/**
375
* The default language.
376
* @default null
377
*/
378
defaultLanguage: string | null | undefined;
379
380
/**
381
* Enable tab key for indentation in code blocks.
382
* @default false
383
*/
384
enableTabIndentation: boolean;
385
386
/**
387
* The number of spaces to use for tab indentation.
388
* @default 4
389
*/
390
tabSize: number;
391
392
/**
393
* Custom HTML attributes that should be added to the rendered HTML tag.
394
* @default {}
395
*/
396
HTMLAttributes: Record<string, any>;
397
}
398
399
interface BulletListOptions {
400
/**
401
* The node name for the list items
402
* @default 'listItem'
403
*/
404
itemTypeName: string;
405
406
/**
407
* HTML attributes to add to the bullet list element
408
* @default {}
409
*/
410
HTMLAttributes: Record<string, any>;
411
412
/**
413
* Keep the marks when splitting the list
414
* @default false
415
*/
416
keepMarks: boolean;
417
418
/**
419
* Keep the attributes when splitting the list
420
* @default false
421
*/
422
keepAttributes: boolean;
423
}
424
425
interface OrderedListOptions {
426
/**
427
* The node name for the list items
428
* @default 'listItem'
429
*/
430
itemTypeName: string;
431
432
/**
433
* HTML attributes to add to the ordered list element
434
* @default {}
435
*/
436
HTMLAttributes: Record<string, any>;
437
438
/**
439
* Keep the marks when splitting the list
440
* @default false
441
*/
442
keepMarks: boolean;
443
444
/**
445
* Keep the attributes when splitting the list
446
* @default false
447
*/
448
keepAttributes: boolean;
449
}
450
451
interface ListItemOptions {
452
/**
453
* The HTML attributes for a list item node.
454
* @default {}
455
*/
456
HTMLAttributes: Record<string, any>;
457
458
/**
459
* The node type for bulletList nodes
460
* @default 'bulletList'
461
*/
462
bulletListTypeName: string;
463
464
/**
465
* The node type for orderedList nodes
466
* @default 'orderedList'
467
*/
468
orderedListTypeName: string;
469
}
470
471
interface ListKeymapOptions {
472
/**
473
* The node type for bulletList nodes
474
* @default 'bulletList'
475
*/
476
bulletListTypeName: string;
477
478
/**
479
* The node type for orderedList nodes
480
* @default 'orderedList'
481
*/
482
orderedListTypeName: string;
483
484
/**
485
* The node type for listItem nodes
486
* @default 'listItem'
487
*/
488
listItemTypeName: string;
489
}
490
491
interface HardBreakOptions {
492
/**
493
* Controls if marks should be kept after being split by a hard break.
494
* @default true
495
*/
496
keepMarks: boolean;
497
498
/**
499
* HTML attributes to add to the hard break element.
500
* @default {}
501
*/
502
HTMLAttributes: Record<string, any>;
503
}
504
505
interface DropcursorOptions {
506
/**
507
* The color of the drop cursor. Use `false` to apply no color and rely only on class.
508
* @default 'currentColor'
509
*/
510
color?: string | false;
511
512
/**
513
* The width of the drop cursor
514
* @default 1
515
*/
516
width: number | undefined;
517
518
/**
519
* The class of the drop cursor
520
* @default undefined
521
*/
522
class: string | undefined;
523
}
524
525
interface TrailingNodeOptions {
526
/**
527
* The node type that should be inserted at the end of the document.
528
* @note the node will always be added to the `notAfter` lists to
529
* prevent an infinite loop.
530
* @default 'paragraph'
531
*/
532
node: string;
533
534
/**
535
* The node types after which the trailing node should not be inserted.
536
* @default ['paragraph']
537
*/
538
notAfter?: string | string[];
539
}
540
541
interface UndoRedoOptions {
542
/**
543
* The amount of history events that are collected before the oldest events are discarded.
544
* @default 100
545
*/
546
depth: number;
547
548
/**
549
* The delay (in milliseconds) between changes after which a new group should be started.
550
* @default 500
551
*/
552
newGroupDelay: number;
553
}
554
555
interface UnderlineOptions {
556
/**
557
* HTML attributes to add to the underline element.
558
* @default {}
559
*/
560
HTMLAttributes: Record<string, any>;
561
}
562
563
interface StrikeOptions {
564
/**
565
* HTML attributes to add to the strike element.
566
* @default {}
567
*/
568
HTMLAttributes: Record<string, any>;
569
}
570
571
interface CodeOptions {
572
/**
573
* The HTML attributes applied to the code element.
574
* @default {}
575
*/
576
HTMLAttributes: Record<string, any>;
577
}
578
579
interface BlockquoteOptions {
580
/**
581
* HTML attributes to add to the blockquote element
582
* @default {}
583
*/
584
HTMLAttributes: Record<string, any>;
585
}
586
587
interface ParagraphOptions {
588
/**
589
* The HTML attributes for a paragraph node.
590
* @default {}
591
*/
592
HTMLAttributes: Record<string, any>;
593
}
594
595
interface HorizontalRuleOptions {
596
/**
597
* The HTML attributes for a horizontal rule node.
598
* @default {}
599
*/
600
HTMLAttributes: Record<string, any>;
601
}
602
603
interface LinkProtocolOptions {
604
scheme: string;
605
optionalSlashes?: boolean;
606
}
607
```
608
609
## Advanced Usage Patterns
610
611
### Extension-Specific Configuration
612
613
```typescript
614
import { Editor } from "@tiptap/core";
615
import StarterKit from "@tiptap/starter-kit";
616
617
const editor = new Editor({
618
extensions: [
619
StarterKit.configure({
620
// Configure heading levels and attributes
621
heading: {
622
levels: [1, 2, 3],
623
HTMLAttributes: {
624
class: "editor-heading",
625
},
626
},
627
628
// Configure link behavior
629
link: {
630
openOnClick: false,
631
autolink: true,
632
protocols: ["http", "https", "mailto"],
633
HTMLAttributes: {
634
class: "editor-link",
635
target: "_blank",
636
rel: "noopener noreferrer",
637
},
638
},
639
640
// Configure code blocks
641
codeBlock: {
642
languageClassPrefix: "language-",
643
exitOnTripleEnter: true,
644
HTMLAttributes: {
645
class: "code-block",
646
},
647
},
648
}),
649
],
650
});
651
```
652
653
### Selective Extension Loading
654
655
```typescript
656
// Only enable text formatting and basic structure
657
const basicEditor = new Editor({
658
extensions: [
659
StarterKit.configure({
660
// Disable lists
661
bulletList: false,
662
orderedList: false,
663
listItem: false,
664
listKeymap: false,
665
666
// Disable advanced features
667
link: false,
668
codeBlock: false,
669
blockquote: false,
670
671
// Keep basic formatting
672
bold: {},
673
italic: {},
674
paragraph: {},
675
heading: { levels: [1, 2] },
676
}),
677
],
678
});
679
```
680
681
### Combining with Additional Extensions
682
683
```typescript
684
import { Editor } from "@tiptap/core";
685
import StarterKit from "@tiptap/starter-kit";
686
import { Image } from "@tiptap/extension-image";
687
import { Table } from "@tiptap/extension-table";
688
689
const fullEditor = new Editor({
690
extensions: [
691
// Use StarterKit as foundation
692
StarterKit.configure({
693
// Configure as needed
694
heading: { levels: [1, 2, 3] },
695
}),
696
697
// Add additional extensions
698
Image.configure({
699
HTMLAttributes: {
700
class: "editor-image",
701
},
702
}),
703
Table.configure({
704
resizable: true,
705
}),
706
],
707
});
708
```