0
# @tiptap/extension-task-item
1

2
Task item extension for Tiptap - enables interactive checkbox list items in rich text editors. This extension allows developers to create todo lists, project management interfaces, and interactive documentation systems within Tiptap rich text editors.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import TaskItem, { TaskItemOptions } from '@tiptap/extension-task-item';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const TaskItem = require('@tiptap/extension-task-item').default;
21
const { TaskItemOptions } = require('@tiptap/extension-task-item');
22
```
23

24
Named imports:
25

26
```typescript
27
import { TaskItem, TaskItemOptions } from '@tiptap/extension-task-item';
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Editor } from '@tiptap/core';
34
import TaskItem from '@tiptap/extension-task-item';
35

36
const editor = new Editor({
37
  extensions: [
38
    TaskItem.configure({
39
      nested: true,
40
      HTMLAttributes: {
41
        class: 'my-task-item',
42
      },
43
    }),
44
  ],
45
  content: `
46
    <li data-type="taskItem" data-checked="false">
47
      <p>Unchecked task item</p>
48
    </li>
49
    <li data-type="taskItem" data-checked="true">
50
      <p>Checked task item</p>
51
    </li>
52
  `,
53
});
54
```
55

56
## Architecture
57

58
The @tiptap/extension-task-item package is built around:
59

60
- **Re-export Pattern**: This package is a convenience wrapper that re-exports TaskItem and TaskItemOptions from @tiptap/extension-list. The actual implementation resides in the extension-list package.
61
- **Tiptap Node Extension**: TaskItem is created using Tiptap's `Node.create()` method, integrating with the ProseMirror document model
62
- **Interactive DOM Rendering**: Custom node view creates interactive checkboxes that update the document state
63
- **Markdown Input Rules**: Automatic parsing of markdown-style task item syntax (- [ ] and - [x])
64
- **Accessibility Support**: Built-in keyboard navigation and customizable aria labels
65
- **Flexible Configuration**: Extensive options for customization including nesting, HTML attributes, and readonly behavior
66

67
## Capabilities
68

69
### TaskItem Node Extension
70

71
The main extension constant for creating task item nodes with interactive checkboxes. TaskItem is created using Tiptap's `Node.create()` method.
72

73
```typescript { .api }
74
const TaskItem: Node<TaskItemOptions>;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import TaskItem from '@tiptap/extension-task-item';
81

82
// Basic usage
83
const taskItem = TaskItem;
84

85
// With configuration
86
const configuredTaskItem = TaskItem.configure({
87
  nested: true,
88
  HTMLAttributes: {
89
    class: 'task-item',
90
    'data-test': 'task-item-element',
91
  },
92
  taskListTypeName: 'myTaskList',
93
});
94

95
// Extended with custom behavior
96
const extendedTaskItem = TaskItem.extend({
97
  addKeyboardShortcuts() {
98
    return {
99
      ...this.parent?.(),
100
      'Ctrl-Enter': () => {
101
        // Custom keyboard shortcut
102
        return this.editor.commands.splitListItem(this.name);
103
      },
104
    };
105
  },
106
});
107
```
108

109
### TaskItem Configuration
110

111
Configuration options interface for customizing TaskItem behavior.
112

113
```typescript { .api }
114
interface TaskItemOptions {
115
  /** Callback for checkbox clicks in readonly mode */
116
  onReadOnlyChecked?: (node: ProseMirrorNode, checked: boolean) => boolean;
117
  
118
  /** Controls whether task items can be nested */
119
  nested: boolean;
120
  
121
  /** HTML attributes to add to the task item element */
122
  HTMLAttributes: Record<string, any>;
123
  
124
  /** Node type name for taskList nodes */
125
  taskListTypeName: string;
126
  
127
  /** Accessibility options for the task item */
128
  a11y?: {
129
    checkboxLabel?: (node: ProseMirrorNode, checked: boolean) => string;
130
  };
131
}
132
```
133

134
**Configuration Examples:**
135

136
```typescript
137
// Basic configuration
138
const basicOptions: TaskItemOptions = {
139
  nested: false,
140
  HTMLAttributes: {},
141
  taskListTypeName: 'taskList',
142
};
143

144
// Advanced configuration with accessibility
145
const advancedOptions: TaskItemOptions = {
146
  nested: true,
147
  HTMLAttributes: {
148
    class: 'interactive-task-item',
149
    'data-testid': 'task-item',
150
  },
151
  taskListTypeName: 'customTaskList',
152
  onReadOnlyChecked: (node, checked) => {
153
    console.log(`Task "${node.textContent}" ${checked ? 'checked' : 'unchecked'}`);
154
    return true; // Allow the change
155
  },
156
  a11y: {
157
    checkboxLabel: (node, checked) => 
158
      `${checked ? 'Completed' : 'Incomplete'} task: ${node.textContent || 'empty task'}`,
159
  },
160
};
161
```
162

163
### Node Attributes
164

165
The TaskItem node includes a single attribute for tracking checkbox state.
166

167
```typescript { .api }
168
interface TaskItemAttributes {
169
  /** Boolean indicating if the task item is checked */
170
  checked: boolean;
171
}
172
```
173

174
### Input Pattern Recognition
175

176
Regular expression constant for matching markdown-style task item input.
177

178
```typescript { .api }
179
const inputRegex: RegExp; // /^\s*(\[([( |x])?\])\s$/
180
```
181

182
The input regex matches patterns like:
183
- `- [ ]` (unchecked task item)  
184
- `- [x]` (checked task item)
185
- `- [X]` (checked task item - case insensitive)
186
- `- [ ]` with extra whitespace
187

188
### Extension Methods
189

190
Core methods available on the TaskItem extension for editor integration. These are internal methods that define the extension's behavior.
191

192
```typescript { .api }
193
interface TaskItemExtensionMethods {
194
  /** Defines allowed content structure based on nesting option */
195
  content(): string;
196
  
197
  /** Returns default configuration options */
198
  addOptions(): TaskItemOptions;
199
  
200
  /** Defines node attributes schema */
201
  addAttributes(): Record<string, Attribute>;
202
  
203
  /** HTML parsing rules for task item elements */
204
  parseHTML(): Array<{ tag: string; priority?: number }>;
205
  
206
  /** Renders task item node to HTML structure */
207
  renderHTML(props: { node: ProseMirrorNode; HTMLAttributes: Record<string, any> }): DOMOutputSpec;
208
  
209
  /** Keyboard shortcuts for task item navigation */
210
  addKeyboardShortcuts(): Record<string, KeyboardShortcutCommand>;
211
  
212
  /** Custom DOM node view with interactive checkbox */
213
  addNodeView(): NodeViewRenderer;
214
  
215
  /** Input rules for markdown-style task items */
216
  addInputRules(): Array<InputRule>;
217
}
218
```
219

220
### Keyboard Shortcuts
221

222
Built-in keyboard shortcuts for task item navigation and manipulation.
223

224
- **Enter**: Split the current task item into two items
225
- **Shift-Tab**: Lift (unindent) the current task item
226
- **Tab**: Sink (indent) the current task item (only when `nested: true`)
227

228
### HTML Structure
229

230
The TaskItem node renders to the following HTML structure:
231

232
```html
233
<li data-type="taskItem" data-checked="false">
234
  <label>
235
    <input type="checkbox" />
236
    <span></span>
237
  </label>
238
  <div>
239
    <!-- Task item content goes here -->
240
  </div>
241
</li>
242
```
243

244
### Error Handling
245

246
The extension handles several edge cases:
247

248
- **Readonly Mode**: When the editor is not editable, checkbox clicks are prevented unless `onReadOnlyChecked` callback is provided
249
- **Invalid State Changes**: The `onReadOnlyChecked` callback can return `false` to reject state changes
250
- **Node Type Validation**: The node view update method validates that updated nodes are of the correct type
251

252
## Types
253

254
```typescript { .api }
255
// Core type imports
256
import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
257
import type { Node, KeyboardShortcutCommand, NodeViewRenderer, InputRule, DOMOutputSpec, Attribute } from '@tiptap/core';
258

259
// TaskItem configuration interface
260
interface TaskItemOptions {
261
  /** Callback for checkbox clicks in readonly mode */
262
  onReadOnlyChecked?: (node: ProseMirrorNode, checked: boolean) => boolean;
263
  /** Controls whether task items can be nested */
264
  nested: boolean;
265
  /** HTML attributes to add to the task item element */
266
  HTMLAttributes: Record<string, any>;
267
  /** Node type name for taskList nodes */
268
  taskListTypeName: string;
269
  /** Accessibility options for the task item */
270
  a11y?: {
271
    checkboxLabel?: (node: ProseMirrorNode, checked: boolean) => string;
272
  };
273
}
274

275
// TaskItem node extension constant
276
const TaskItem: Node<TaskItemOptions>;
277

278
// Input pattern constant for markdown-style task items
279
const inputRegex: RegExp;
280

281
// TaskItem node attributes
282
interface TaskItemAttributes {
283
  checked: boolean;
284
}
285
```