0
# @tiptap/extension-bullet-list
1

2
@tiptap/extension-bullet-list provides bullet list functionality for Tiptap rich text editors. This extension enables the creation and management of unordered lists with bullet points, integrating seamlessly with Tiptap's headless editor architecture built on ProseMirror.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { BulletList } from '@tiptap/extension-bullet-list';
15
import type { BulletListOptions } from '@tiptap/extension-bullet-list';
16
```
17

18
Default import:
19
```typescript
20
import BulletList from '@tiptap/extension-bullet-list';
21
```
22

23
For CommonJS:
24
```javascript
25
const { BulletList } = require('@tiptap/extension-bullet-list');
26
```
27

28
Type-only import:
29
```typescript
30
import type { BulletListOptions } from '@tiptap/extension-bullet-list';
31
```
32

33
Import regex pattern from extension-list:
34
```typescript
35
import { bulletListInputRegex } from '@tiptap/extension-list';
36
```
37

38
## Basic Usage
39

40
```typescript
41
import { Editor } from '@tiptap/core';
42
import { BulletList } from '@tiptap/extension-bullet-list';
43
import { ListItem } from '@tiptap/extension-list-item';
44

45
const editor = new Editor({
46
  extensions: [
47
    BulletList,
48
    ListItem, // Required dependency
49
  ],
50
  content: '<ul><li>First item</li><li>Second item</li></ul>',
51
});
52

53
// Toggle bullet list programmatically
54
editor.chain().focus().toggleBulletList().run();
55

56
// Use keyboard shortcut: Mod-Shift-8
57
// Or type "- " at the beginning of a line for auto-conversion
58
```
59

60
## Capabilities
61

62
### BulletList Extension
63

64
The main extension class that provides bullet list functionality.
65

66
```typescript { .api }
67
const BulletList: Node<BulletListOptions>;
68
```
69

70
### Configuration Options
71

72
Options for customizing bullet list behavior.
73

74
```typescript { .api }
75
interface BulletListOptions {
76
  /** 
77
   * The node name for the list items
78
   * @default 'listItem'
79
   */
80
  itemTypeName: string;
81
  
82
  /** 
83
   * HTML attributes to add to the bullet list element
84
   * @default {}
85
   */
86
  HTMLAttributes: Record<string, any>;
87
  
88
  /** 
89
   * Keep the marks when splitting the list
90
   * @default false
91
   */
92
  keepMarks: boolean;
93
  
94
  /** 
95
   * Keep the attributes when splitting the list
96
   * @default false
97
   */
98
  keepAttributes: boolean;
99
}
100
```
101

102
**Usage with options:**
103

104
```typescript
105
import { BulletList } from '@tiptap/extension-bullet-list';
106

107
const editor = new Editor({
108
  extensions: [
109
    BulletList.configure({
110
      HTMLAttributes: {
111
        class: 'my-bullet-list',
112
      },
113
      keepMarks: true,
114
      keepAttributes: true,
115
    }),
116
  ],
117
});
118
```
119

120
### Commands
121

122
Commands available through the editor instance for bullet list manipulation.
123

124
```typescript { .api }
125
interface Commands {
126
  bulletList: {
127
    /** Toggle a bullet list */
128
    toggleBulletList(): Command;
129
  };
130
}
131
```
132

133
**Usage:**
134

135
```typescript
136
// Toggle bullet list on current selection
137
editor.commands.toggleBulletList();
138

139
// Chain with other commands
140
editor.chain().focus().toggleBulletList().run();
141
```
142

143
### Input Rules
144

145
The BulletList extension includes automatic input rules that convert typed patterns into bullet lists. The extension automatically converts lines starting with `- `, `+ `, or `* ` into bullet lists.
146

147
```typescript { .api }
148
const bulletListInputRegex: RegExp;
149
```
150

151
**Usage:**
152

153
```typescript
154
import { bulletListInputRegex } from '@tiptap/extension-list';
155

156
// The regex pattern matches: /^\s*([-+*])\s$/
157
console.log(bulletListInputRegex.test('- ')); // true
158
console.log(bulletListInputRegex.test('+ ')); // true  
159
console.log(bulletListInputRegex.test('* ')); // true
160
```
161

162
### Keyboard Shortcuts
163

164
Built-in keyboard shortcuts for bullet list operations.
165

166
| Shortcut | Action |
167
|----------|--------|
168
| `Mod-Shift-8` | Toggle bullet list |
169
170
Where `Mod` is `Cmd` on macOS and `Ctrl` on other platforms.
171

172
## Node Properties
173

174
The BulletList node has the following characteristics:
175

176
- **Name**: `bulletList`
177
- **Group**: `block list`
178
- **Content**: Accepts one or more list items (defined by `itemTypeName` option)
179
- **HTML Parsing**: Parses `<ul>` elements
180
- **HTML Rendering**: Outputs `<ul>` elements with merged attributes
181

182
## Dependencies
183

184
This extension requires:
185

186
- **@tiptap/extension-list**: Peer dependency providing the actual BulletList implementation
187
- **@tiptap/extension-list-item**: Required for list item functionality (must be installed separately)
188
- **@tiptap/core**: Core Tiptap framework
189

190
**Complete installation:**
191

192
```bash
193
npm install @tiptap/extension-bullet-list @tiptap/extension-list-item @tiptap/core
194
```
195

196
## Error Handling
197

198
The extension integrates with Tiptap's command system. Commands return `true` on success and `false` on failure:
199

200
```typescript
201
const success = editor.commands.toggleBulletList();
202
if (!success) {
203
  console.log('Failed to toggle bullet list');
204
}
205
```
206

207
## Advanced Usage
208

209
### Custom List Item Types
210

211
```typescript
212
import { BulletList } from '@tiptap/extension-bullet-list';
213

214
const editor = new Editor({
215
  extensions: [
216
    BulletList.configure({
217
      itemTypeName: 'customListItem',
218
    }),
219
  ],
220
});
221
```
222

223
### Preserving Formatting
224

225
```typescript
226
const editor = new Editor({
227
  extensions: [
228
    BulletList.configure({
229
      keepMarks: true,      // Preserve text formatting
230
      keepAttributes: true, // Preserve node attributes
231
    }),
232
  ],
233
});
234
```
235

236
### Custom HTML Attributes
237

238
```typescript
239
const editor = new Editor({
240
  extensions: [
241
    BulletList.configure({
242
      HTMLAttributes: {
243
        class: 'custom-bullet-list',
244
        'data-type': 'bullet-list',
245
      },
246
    }),
247
  ],
248
});
249
```