0
# Tiptap Blockquote Extension
1

2
The Tiptap Blockquote Extension provides blockquote functionality for the Tiptap rich text editor framework. It allows users to create, toggle, and manipulate blockquote elements with keyboard shortcuts, input rules, and programmatic commands.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Blockquote } from '@tiptap/extension-blockquote';
15
```
16

17
For default import:
18

19
```typescript
20
import Blockquote from '@tiptap/extension-blockquote';
21
```
22

23
For importing additional exports:
24

25
```typescript
26
import { Blockquote, inputRegex, type BlockquoteOptions } from '@tiptap/extension-blockquote';
27
```
28

29
For CommonJS:
30

31
```javascript
32
const { Blockquote } = require('@tiptap/extension-blockquote');
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { Editor } from '@tiptap/core';
39
import { Blockquote } from '@tiptap/extension-blockquote';
40

41
const editor = new Editor({
42
  extensions: [
43
    Blockquote.configure({
44
      HTMLAttributes: {
45
        class: 'my-custom-blockquote',
46
      },
47
    }),
48
  ],
49
  content: '<p>Type > and a space to create a blockquote</p>',
50
});
51

52
// Use commands programmatically
53
editor.commands.setBlockquote();        // Wrap selection in blockquote
54
editor.commands.toggleBlockquote();     // Toggle blockquote
55
editor.commands.unsetBlockquote();      // Remove blockquote wrapping
56
```
57

58
## Capabilities
59

60
### Extension Class
61

62
The main Blockquote extension that integrates with Tiptap's node system.
63

64
```typescript { .api }
65
/**
66
 * Blockquote extension for Tiptap editor
67
 * Provides blockquote functionality with commands, keyboard shortcuts, and input rules
68
 */
69
const Blockquote: Node<BlockquoteOptions, any>;
70
```
71

72
### Configuration Options
73

74
Configure the blockquote extension behavior and HTML attributes.
75

76
```typescript { .api }
77
interface BlockquoteOptions {
78
  /**
79
   * HTML attributes to add to the blockquote element
80
   * @default {}
81
   * @example { class: 'foo' }
82
   */
83
  HTMLAttributes: Record<string, any>;
84
}
85
```
86

87
**Usage Example:**
88

89
```typescript
90
import { Blockquote } from '@tiptap/extension-blockquote';
91

92
const editor = new Editor({
93
  extensions: [
94
    Blockquote.configure({
95
      HTMLAttributes: {
96
        class: 'prose-blockquote',
97
        'data-type': 'blockquote',
98
      },
99
    }),
100
  ],
101
});
102
```
103

104
### Commands
105

106
The extension adds three commands to the editor's command system.
107

108
```typescript { .api }
109
interface Commands {
110
  blockQuote: {
111
    /**
112
     * Set a blockquote node - wraps the current selection in a blockquote
113
     * @returns Command function that returns boolean indicating success
114
     */
115
    setBlockquote(): Command;
116
    /**
117
     * Toggle a blockquote node - toggles blockquote wrapping on selection
118
     * @returns Command function that returns boolean indicating success
119
     */
120
    toggleBlockquote(): Command;
121
    /**
122
     * Unset a blockquote node - removes blockquote wrapping from selection
123
     * @returns Command function that returns boolean indicating success
124
     */
125
    unsetBlockquote(): Command;
126
  };
127
}
128
```
129

130
**Usage Examples:**
131

132
```typescript
133
// Wrap current selection in blockquote
134
if (editor.commands.setBlockquote()) {
135
  console.log('Successfully created blockquote');
136
}
137

138
// Toggle blockquote (create if none, remove if exists)
139
editor.commands.toggleBlockquote();
140

141
// Remove blockquote wrapping
142
editor.commands.unsetBlockquote();
143

144
// Check if current selection can be wrapped in blockquote
145
if (editor.can().setBlockquote()) {
146
  editor.commands.setBlockquote();
147
}
148
```
149

150
### Input Rules
151

152
The extension automatically creates blockquotes when users type the trigger pattern.
153

154
```typescript { .api }
155
/**
156
 * Regular expression that matches blockquote input trigger
157
 * Matches "> " at the beginning of a line (with optional whitespace)
158
 */
159
const inputRegex: RegExp;
160
```
161

162
**Behavior:**
163
- Typing `>` followed by a space at the start of a line automatically creates a blockquote
164
- The `>` and space are consumed and replaced with the blockquote structure
165

166
### Keyboard Shortcuts
167

168
The extension provides keyboard shortcuts for quick blockquote manipulation.
169

170
**Available Shortcuts:**
171
- `Mod-Shift-b`: Toggle blockquote (⌘⇧B on Mac, Ctrl+Shift+B on Windows/Linux)
172

173
### Node Properties
174

175
The blockquote node has the following ProseMirror characteristics:
176

177
- **Name**: `'blockquote'`
178
- **Content**: `'block+'` (contains one or more block-level elements)
179
- **Group**: `'block'` (belongs to the block content group)
180
- **Defining**: `true` (creates structural boundaries in the document)
181

182
### HTML Integration
183

184
The extension handles HTML parsing and rendering:
185

186
**HTML Parsing:**
187
- Recognizes `<blockquote>` elements when parsing HTML content
188
- Preserves existing blockquote structure during content import
189

190
**HTML Rendering:**
191
- Renders as semantic `<blockquote>` elements
192
- Merges configured HTMLAttributes with any runtime attributes
193
- Maintains proper nesting of block content within blockquotes
194

195
## Types
196

197
```typescript { .api }
198
interface BlockquoteOptions {
199
  HTMLAttributes: Record<string, any>;
200
}
201

202
type Command = (props: {
203
  editor: Editor;
204
  tr: Transaction;
205
  commands: Commands;
206
  can: () => Commands;
207
  chain: () => Commands;
208
  state: EditorState;
209
  dispatch: ((tr: Transaction) => void) | undefined;
210
  view: EditorView;
211
}) => boolean;
212
```
213

214
## Error Handling
215

216
The extension follows Tiptap's standard error handling patterns:
217

218
- Commands return `boolean` values indicating success/failure
219
- Failed operations (e.g., trying to create blockquote in invalid context) return `false`
220
- No exceptions are thrown during normal operation
221
- Invalid configurations are handled gracefully with fallback to defaults