0
# Tiptap Extension List Item
1

2
The @tiptap/extension-list-item package provides list item functionality for Tiptap rich text editors. It enables creation and management of list items (`<li>` elements) that work seamlessly with bullet lists and ordered lists.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { ListItem } from '@tiptap/extension-list-item';
15
import type { ListItemOptions } from '@tiptap/extension-list-item';
16
```
17

18
Default import:
19

20
```typescript
21
import ListItem from '@tiptap/extension-list-item';
22
```
23

24
CommonJS:
25

26
```javascript
27
const { ListItem } = require('@tiptap/extension-list-item');
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Editor } from '@tiptap/core';
34
import { ListItem } from '@tiptap/extension-list-item';
35
import { BulletList } from '@tiptap/extension-bullet-list';
36
import { OrderedList } from '@tiptap/extension-ordered-list';
37

38
const editor = new Editor({
39
  extensions: [
40
    ListItem,
41
    BulletList,
42
    OrderedList,
43
  ],
44
  content: `
45
    <ul>
46
      <li>First item</li>
47
      <li>Second item</li>
48
    </ul>
49
  `,
50
});
51
```
52

53
## Architecture
54

55
The ListItem extension is built on Tiptap's Node architecture and provides:
56

57
- **Node Definition**: Defines the `listItem` node type with proper parsing and rendering
58
- **Content Model**: Supports paragraph followed by zero or more block elements (`paragraph block*`)
59
- **Keyboard Shortcuts**: Built-in shortcuts for Enter, Tab, and Shift-Tab
60
- **List Integration**: Works with BulletList and OrderedList extensions
61

62
## Capabilities
63

64
### ListItem Node Extension
65

66
Creates a Tiptap node extension that handles list item functionality.
67

68
```typescript { .api }
69
import type { Node } from '@tiptap/core';
70

71
/**
72
 * List item node extension for Tiptap editors
73
 * Enables creation and management of <li> elements
74
 */
75
const ListItem: Node<ListItemOptions>;
76
```
77

78
### Configuration Options
79

80
Options interface for configuring the ListItem extension.
81

82
```typescript { .api }
83
interface ListItemOptions {
84
  /**
85
   * The HTML attributes for a list item node.
86
   * @default {}
87
   * @example { class: 'custom-list-item' }
88
   */
89
  HTMLAttributes: Record<string, any>;
90

91
  /**
92
   * The node type for bulletList nodes
93
   * @default 'bulletList'
94
   * @example 'myCustomBulletList'
95
   */
96
  bulletListTypeName: string;
97

98
  /**
99
   * The node type for orderedList nodes  
100
   * @default 'orderedList'
101
   * @example 'myCustomOrderedList'
102
   */
103
  orderedListTypeName: string;
104
}
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import { Editor } from '@tiptap/core';
111
import { ListItem } from '@tiptap/extension-list-item';
112

113
// Basic configuration
114
const editor = new Editor({
115
  extensions: [
116
    ListItem,
117
  ],
118
});
119

120
// Custom configuration
121
const editor = new Editor({
122
  extensions: [
123
    ListItem.configure({
124
      HTMLAttributes: {
125
        class: 'my-list-item',
126
      },
127
      bulletListTypeName: 'customBulletList',
128
      orderedListTypeName: 'customOrderedList',
129
    }),
130
  ],
131
});
132
```
133

134
### Node Properties
135

136
The ListItem node has the following built-in properties:
137

138
```typescript { .api }
139
interface ListItemNode {
140
  /** Node name identifier */
141
  name: 'listItem';
142
  
143
  /** Content expression - allows paragraph followed by zero or more blocks */
144
  content: 'paragraph block*';
145
  
146
  /** Defining property - this node defines its content structure */
147
  defining: boolean;
148
  
149
  /** Parse HTML configuration - recognizes <li> tags */
150
  parseHTML(): Array<{ tag: string }>;
151
  
152
  /** Render HTML configuration - outputs <li> elements */
153
  renderHTML(options: { HTMLAttributes: Record<string, any> }): [string, Record<string, any>, number];
154
}
155
```
156

157
### Keyboard Shortcuts
158

159
Built-in keyboard shortcuts for list item management:
160

161
```typescript { .api }
162
interface ListItemKeyboardShortcuts {
163
  /** Split list item at cursor position */
164
  'Enter': () => boolean;
165
  
166
  /** Indent/nest list item */
167
  'Tab': () => boolean;
168
  
169
  /** Outdent/lift list item */
170
  'Shift-Tab': () => boolean;
171
}
172
```
173

174
**Keyboard Shortcut Behaviors:**
175

176
- **Enter**: Splits the current list item, creating a new list item below
177
- **Tab**: Indents the current list item (requires parent list to support nesting)
178
- **Shift-Tab**: Outdents the current list item, moving it up one level
179

180
### Editor Commands Integration
181

182
When ListItem is installed, it enables these commands on the editor:
183

184
```typescript
185
// Split current list item
186
editor.commands.splitListItem('listItem');
187

188
// Indent current list item  
189
editor.commands.sinkListItem('listItem');
190

191
// Outdent current list item
192
editor.commands.liftListItem('listItem');
193
```
194

195
## Error Handling
196

197
The ListItem extension handles common edge cases:
198

199
- **Invalid nesting**: Prevents invalid list structures
200
- **Content validation**: Ensures list items contain valid content
201
- **Command failures**: Commands return boolean indicating success/failure
202

203
## Dependencies
204

205
### Peer Dependencies
206

207
- **@tiptap/extension-list**: Required for the actual ListItem implementation
208
- **@tiptap/core**: Provides the Node base class and editor functionality
209

210
### Typical Usage Dependencies
211

212
- **@tiptap/extension-bullet-list**: For unordered lists
213
- **@tiptap/extension-ordered-list**: For ordered lists
214
- **@tiptap/extension-paragraph**: For paragraph content within list items