0
# Extensions
1

2
Tiptap extensions with enhanced functionality for links and task lists. These extensions provide additional features beyond the standard Tiptap extensions, including custom keyboard shortcuts and styling integration.
3

4
## Capabilities
5

6
### Link Extension
7

8
Enhanced Tiptap Link extension with custom keyboard shortcuts and optimized behavior for rich text editing.
9

10
```typescript { .api }
11
/**
12
 * Enhanced Link extension with keyboard shortcuts
13
 * Extends @tiptap/extension-link with additional functionality
14
 * Keyboard shortcut: Ctrl/Cmd + K opens link editor
15
 */
16
const Link: Extension;
17
```
18

19
**Features:**
20
- **Keyboard Shortcut**: Cmd/Ctrl+K opens link editing interface
21
- **Click Behavior**: Links don't open on click (optimized for editing)
22
- **Event Integration**: Dispatches 'edit-link' window event for UI integration
23

24
**Usage Example:**
25

26
```typescript
27
import { useEditor } from "@tiptap/react";
28
import StarterKit from "@tiptap/starter-kit";
29
import { RichTextEditor, Link } from "@mantine/tiptap";
30

31
function EditorWithLinks() {
32
  const editor = useEditor({
33
    extensions: [
34
      StarterKit,
35
      Link, // Enhanced Link extension
36
    ],
37
    content: '<p>Visit <a href="https://mantine.dev">Mantine</a> for more info!</p>',
38
  });
39

40
  return (
41
    <RichTextEditor editor={editor}>
42
      <RichTextEditor.Toolbar>
43
        <RichTextEditor.ControlsGroup>
44
          <RichTextEditor.Link />
45
          <RichTextEditor.Unlink />
46
        </RichTextEditor.ControlsGroup>
47
      </RichTextEditor.Toolbar>
48
      <RichTextEditor.Content />
49
    </RichTextEditor>
50
  );
51
}
52
```
53

54
### TaskList Extension Factory
55

56
Factory function that enhances any Tiptap TaskList extension with custom keyboard shortcuts and Mantine-specific styling.
57

58
```typescript { .api }
59
/**
60
 * Factory function to enhance TaskList extensions
61
 * Adds keyboard shortcuts and custom styling to any TaskList extension
62
 * @param TipTapTaskList - The TaskList extension to enhance
63
 * @returns Enhanced TaskList extension with additional functionality
64
 */
65
function getTaskListExtension<T>(TipTapTaskList: T): T;
66
```
67

68
**Features:**
69
- **Keyboard Shortcuts**: 
70
  - `Cmd/Ctrl + [`: Decrease task indentation (lift)
71
  - `Cmd/Ctrl + ]`: Increase task indentation (sink)
72
- **Custom Styling**: Applies Mantine-specific CSS classes
73
- **Generic Support**: Works with any TaskList extension implementation
74

75
**Usage Example:**
76

77
```typescript
78
import { useEditor } from "@tiptap/react";
79
import StarterKit from "@tiptap/starter-kit";
80
import TaskList from "@tiptap/extension-task-list";
81
import TaskItem from "@tiptap/extension-task-item";
82
import { RichTextEditor, getTaskListExtension } from "@mantine/tiptap";
83

84
function EditorWithTasks() {
85
  const editor = useEditor({
86
    extensions: [
87
      StarterKit,
88
      // Enhanced TaskList with keyboard shortcuts and styling
89
      getTaskListExtension(TaskList),
90
      TaskItem.configure({
91
        nested: true,
92
      }),
93
    ],
94
    content: `
95
      <ul data-type="taskList">
96
        <li data-type="taskItem" data-checked="false">Uncompleted task</li>
97
        <li data-type="taskItem" data-checked="true">Completed task</li>
98
        <li data-type="taskItem" data-checked="false">
99
          Parent task
100
          <ul data-type="taskList">
101
            <li data-type="taskItem" data-checked="false">Nested task</li>
102
          </ul>
103
        </li>
104
      </ul>
105
    `,
106
  });
107

108
  return (
109
    <RichTextEditor editor={editor}>
110
      <RichTextEditor.Toolbar>
111
        <RichTextEditor.ControlsGroup>
112
          <RichTextEditor.TaskList />
113
          <RichTextEditor.TaskListSink />
114
          <RichTextEditor.TaskListLift />
115
        </RichTextEditor.ControlsGroup>
116
      </RichTextEditor.Toolbar>
117
      <RichTextEditor.Content />
118
    </RichTextEditor>
119
  );
120
}
121
```
122

123
## Extension Details
124

125
### Link Extension Implementation
126

127
The Link extension is built on top of `@tiptap/extension-link` with the following enhancements:
128

129
```typescript
130
// Internal implementation (for reference)
131
import TipTapLink from '@tiptap/extension-link';
132

133
const Link = TipTapLink.extend({
134
  addKeyboardShortcuts: () => ({
135
    'Mod-k': () => {
136
      // Dispatches custom event for UI integration
137
      window.dispatchEvent(new Event('edit-link'));
138
      return true;
139
    },
140
  }),
141
}).configure({ 
142
  openOnClick: false // Prevents links from opening when clicked
143
});
144
```
145

146
**Configuration Options:**
147
- All standard `@tiptap/extension-link` options are supported
148
- `openOnClick: false` is set by default for better editing experience
149
- Additional keyboard shortcuts are automatically added
150

151
### TaskList Extension Factory Implementation
152

153
The factory function enhances TaskList extensions with:
154

155
```typescript
156
// Internal implementation (for reference)  
157
const getTaskListExtension = <T>(TipTapTaskList: T): T =>
158
  (TipTapTaskList as any)
159
    .extend({
160
      addKeyboardShortcuts: () => ({
161
        'Mod-[': ({ editor }: any) => {
162
          editor.chain().focus().liftListItem('taskItem').run();
163
          return true;
164
        },
165
        'Mod-]': ({ editor }: any) => {
166
          editor.chain().focus().sinkListItem('taskItem').run();
167
          return true;
168
        },
169
      }),
170
    })
171
    .configure({
172
      HTMLAttributes: {
173
        class: `mantine-RichTextEditor-taskList`,
174
      },
175
    });
176
```
177

178
**Enhancement Features:**
179
- **Keyboard Shortcuts**: Standard indentation shortcuts for task management
180
- **CSS Classes**: Mantine-specific classes for consistent styling
181
- **Generic Implementation**: Works with any TaskList extension
182

183
## Complete Extensions Example
184

185
```typescript
186
import { useEditor } from "@tiptap/react";
187
import StarterKit from "@tiptap/starter-kit";
188
import TaskList from "@tiptap/extension-task-list";
189
import TaskItem from "@tiptap/extension-task-item";
190
import { RichTextEditor, Link, getTaskListExtension } from "@mantine/tiptap";
191

192
function FullFeaturedEditor() {
193
  const editor = useEditor({
194
    extensions: [
195
      StarterKit,
196
      
197
      // Enhanced Link extension
198
      Link,
199
      
200
      // Enhanced TaskList extension
201
      getTaskListExtension(TaskList),
202
      TaskItem.configure({
203
        nested: true,
204
        HTMLAttributes: {
205
          class: 'my-task-item',
206
        },
207
      }),
208
    ],
209
    content: `
210
      <h2>Rich Text Editor with Extensions</h2>
211
      
212
      <p>This editor supports <a href="https://mantine.dev">enhanced links</a> 
213
      with keyboard shortcuts (Cmd/Ctrl+K).</p>
214
      
215
      <p>Task management with enhanced shortcuts:</p>
216
      <ul data-type="taskList">
217
        <li data-type="taskItem" data-checked="false">
218
          Press Cmd/Ctrl+] to indent this task
219
        </li>
220
        <li data-type="taskItem" data-checked="true">
221
          Press Cmd/Ctrl+[ to outdent this task
222
        </li>
223
        <li data-type="taskItem" data-checked="false">
224
          Parent task
225
          <ul data-type="taskList">
226
            <li data-type="taskItem" data-checked="false">Nested subtask</li>
227
          </ul>
228
        </li>
229
      </ul>
230
    `,
231
  });
232

233
  return (
234
    <RichTextEditor editor={editor}>
235
      <RichTextEditor.Toolbar sticky stickyOffset={60}>
236
        {/* Link controls */}
237
        <RichTextEditor.ControlsGroup>
238
          <RichTextEditor.Link />
239
          <RichTextEditor.Unlink />
240
        </RichTextEditor.ControlsGroup>
241

242
        {/* Task controls */}
243
        <RichTextEditor.ControlsGroup>
244
          <RichTextEditor.TaskList />
245
          <RichTextEditor.TaskListSink />
246
          <RichTextEditor.TaskListLift />
247
        </RichTextEditor.ControlsGroup>
248
      </RichTextEditor.Toolbar>
249

250
      <RichTextEditor.Content />
251
    </RichTextEditor>
252
  );
253
}
254
```
255

256
## Extension Integration
257

258
### Event Handling
259

260
The Link extension dispatches custom events that can be handled by your application:
261

262
```typescript
263
useEffect(() => {
264
  const handleEditLink = () => {
265
    console.log('Link editing triggered');
266
    // Custom link editing logic
267
  };
268

269
  window.addEventListener('edit-link', handleEditLink);
270
  
271
  return () => {
272
    window.removeEventListener('edit-link', handleEditLink);
273
  };
274
}, []);
275
```
276

277
### Styling Integration
278

279
Extensions automatically integrate with Mantine's styling system:
280

281
```typescript
282
// TaskList extension applies these classes automatically
283
.mantine-RichTextEditor-taskList {
284
  /* Mantine task list styling */
285
}
286

287
// You can override with custom styles
288
<RichTextEditor
289
  styles={{
290
    taskList: {
291
      marginLeft: '1rem',
292
      '& li': {
293
        marginBottom: '0.5rem',
294
      },
295
    },
296
  }}
297
>
298
  {/* editor content */}
299
</RichTextEditor>
300
```
301

302
### Custom Extension Development
303

304
You can create your own enhanced extensions using similar patterns:
305

306
```typescript
307
import { Extension } from '@tiptap/core';
308

309
const MyCustomExtension = Extension.create({
310
  name: 'myCustom',
311
  
312
  addKeyboardShortcuts() {
313
    return {
314
      'Mod-Shift-x': () => {
315
        // Custom functionality
316
        return true;
317
      },
318
    };
319
  },
320
  
321
  addOptions() {
322
    return {
323
      HTMLAttributes: {
324
        class: 'mantine-RichTextEditor-custom',
325
      },
326
    };
327
  },
328
});
329

330
// Use with RichTextEditor
331
const editor = useEditor({
332
  extensions: [StarterKit, MyCustomExtension],
333
});
334
```
335

336
## Required Dependencies
337

338
Extensions require specific Tiptap packages:
339

340
- **Link Extension**: 
341
  - `@tiptap/extension-link` (peer dependency)
342
  - Automatically imported when using `Link` from `@mantine/tiptap`
343

344
- **TaskList Extension Factory**:
345
  - `@tiptap/extension-task-list`
346
  - `@tiptap/extension-task-item`
347
  - Must be installed and passed to `getTaskListExtension()`
348

349
## Best Practices
350

351
### Extension Ordering
352

353
```typescript
354
const editor = useEditor({
355
  extensions: [
356
    StarterKit, // Base extensions first
357
    Link, // Enhanced Link extension
358
    getTaskListExtension(TaskList), // Enhanced TaskList
359
    TaskItem, // TaskItem after TaskList
360
    // Other extensions...
361
  ],
362
});
363
```
364

365
### Configuration
366

367
```typescript
368
// Configure enhanced extensions
369
const editor = useEditor({
370
  extensions: [
371
    StarterKit,
372
    Link, // Uses default configuration
373
    getTaskListExtension(
374
      TaskList.configure({
375
        itemTypeName: 'taskItem',
376
        HTMLAttributes: {
377
          class: 'custom-task-list',
378
        },
379
      })
380
    ),
381
  ],
382
});
383
```
384

385
### TypeScript Support
386

387
```typescript
388
import type { Extension } from '@tiptap/core';
389
import { Link, getTaskListExtension } from '@mantine/tiptap';
390

391
// Extensions have proper TypeScript support
392
const linkExtension: Extension = Link;
393
const taskListExtension: Extension = getTaskListExtension(TaskList);
394
```