0
# List Transforms
1

2
Transform operations for manipulating list formatting, indentation, and structure. These functions modify the editor state to create, modify, or remove list formatting.
3

4
## Capabilities
5

6
### toggleList
7

8
Toggles list formatting on selected blocks. This is the primary function for adding or removing list formatting.
9

10
```typescript { .api }
11
/**
12
 * Toggles list formatting on selected blocks
13
 * @param editor - The Slate editor instance
14
 * @param options - Options for list configuration
15
 * @param getSiblingListOptions - Options for sibling list queries
16
 */
17
function toggleList<N extends ElementOf<E>, E extends SlateEditor = SlateEditor>(
18
  editor: E,
19
  options: ListOptions,
20
  getSiblingListOptions?: GetSiblingListOptions<N, E>
21
): void;
22
```
23

24
**Usage Example:**
25

26
```typescript
27
import { toggleList, ListStyleType } from "@udecode/plate-list";
28

29
// Toggle bullet list
30
toggleList(editor, {
31
  listStyleType: ListStyleType.Disc,
32
});
33

34
// Toggle numbered list
35
toggleList(editor, {
36
  listStyleType: ListStyleType.Decimal,
37
});
38

39
// Toggle list with custom restart number
40
toggleList(editor, {
41
  listStyleType: ListStyleType.Decimal,
42
  listRestart: 5, // Start numbering from 5
43
});
44
```
45

46
### indentList
47

48
Increases the indentation of selected blocks, creating nested list structure.
49

50
```typescript { .api }
51
/**
52
 * Increases the indentation of selected blocks
53
 * @param editor - The Slate editor instance
54
 * @param options - Options for list configuration
55
 */
56
function indentList(
57
  editor: SlateEditor, 
58
  options?: { listStyleType?: ListStyleType | string } & ListOptions
59
): void;
60
```
61

62
**Usage Example:**
63

64
```typescript
65
import { indentList, ListStyleType } from "@udecode/plate-list";
66

67
// Simple indentation
68
indentList(editor);
69

70
// Indent with specific list style
71
indentList(editor, {
72
  listStyleType: ListStyleType.Circle,
73
});
74
```
75

76
### outdentList
77

78
Decreases the indentation of selected blocks, reducing nesting level.
79

80
```typescript { .api }
81
/**
82
 * Decreases the indentation of selected blocks
83
 * @param editor - The Slate editor instance
84
 * @param options - Options for list configuration
85
 */
86
function outdentList(editor: SlateEditor, options: ListOptions = {}): void;
87
```
88

89
**Usage Example:**
90

91
```typescript
92
import { outdentList } from "@udecode/plate-list";
93

94
// Simple outdentation
95
outdentList(editor);
96

97
// Outdent with options
98
outdentList(editor, {
99
  at: specificPath, // Target specific location
100
});
101
```
102

103
### indentTodo
104

105
Increases indentation and converts to todo list format.
106

107
```typescript { .api }
108
/**
109
 * Increases indentation and converts to todo list
110
 * @param editor - The Slate editor instance
111
 * @param options - Options for list configuration
112
 */
113
function indentTodo(
114
  editor: SlateEditor, 
115
  options: ListOptions = {}
116
): void;
117
```
118

119
**Usage Example:**
120

121
```typescript
122
import { indentTodo } from "@udecode/plate-list";
123

124
// Convert to todo list with indentation
125
indentTodo(editor);
126
```
127

128
### setListNode
129

130
Sets a single node as a list item with specified properties.
131

132
```typescript { .api }
133
/**
134
 * Sets a single node as a list item
135
 * @param editor - The Slate editor instance
136
 * @param options - Options including path, indent, and list style type
137
 */
138
function setListNode(
139
  editor: Editor,
140
  options: {
141
    at: Path;
142
    indent?: number;
143
    listStyleType?: string;
144
  }
145
): void;
146
```
147

148
### setIndentTodoNode
149

150
Sets a single node as a todo list item with checkbox functionality.
151

152
```typescript { .api }
153
/**
154
 * Sets a single node as a todo list item with checkbox functionality
155
 * @param editor - The Slate editor instance
156
 * @param options - Options including path, indent, and list style type
157
 */
158
function setIndentTodoNode(
159
  editor: Editor,
160
  options: {
161
    at: Path;
162
    indent?: number;
163
    listStyleType?: string;
164
  }
165
): void;
166
```
167

168
**Usage Example:**
169

170
```typescript
171
import { setIndentTodoNode } from "@udecode/plate-list";
172

173
// Convert specific node to todo list item
174
setIndentTodoNode(editor, {
175
  at: [0, 1], // Path to target node
176
  indent: 2,
177
  listStyleType: 'todo'
178
});
179
```
180

181
### setListNodes
182

183
Sets multiple nodes as list items with the same formatting.
184

185
```typescript { .api }
186
/**
187
 * Sets multiple nodes as list items
188
 * @param editor - The Slate editor instance
189
 * @param entries - Array of node entries to convert
190
 * @param options - Options including list style type
191
 */
192
function setListNodes(
193
  editor: Editor,
194
  entries: NodeEntry[],
195
  options: { listStyleType?: string }
196
): void;
197
```
198

199
**Usage Example:**
200

201
```typescript
202
import { setListNodes, ListStyleType } from "@udecode/plate-list";
203

204
// Get selected nodes
205
const entries = Array.from(Editor.nodes(editor, {
206
  match: n => Element.isElement(n) && !n.listStyleType
207
}));
208

209
// Convert all to bullet lists
210
setListNodes(editor, entries, {
211
  listStyleType: ListStyleType.Disc
212
});
213
```
214

215
### setListSiblingNodes
216

217
Sets list properties on an entry and its siblings based on sibling list options.
218

219
```typescript { .api }
220
/**
221
 * Sets list properties on entry and its siblings
222
 * @param editor - The Slate editor instance
223
 * @param entry - The reference entry
224
 * @param options - Options for sibling detection and list style type
225
 */
226
function setListSiblingNodes<N extends ElementOf<E>, E extends Editor = Editor>(
227
  editor: E,
228
  entry: ElementEntryOf<E>,
229
  options: {
230
    getSiblingListOptions?: GetSiblingListOptions<N, E>;
231
    listStyleType?: string;
232
  }
233
): void;
234
```
235

236
### toggleListByPath
237

238
Toggles list formatting at a specific path in the document.
239

240
```typescript { .api }
241
/**
242
 * Toggles list formatting at a specific path
243
 * @param editor - The Slate editor instance
244
 * @param entry - The node entry to toggle
245
 * @param listStyleType - The list style type to apply
246
 */
247
function toggleListByPath(
248
  editor: SlateEditor,
249
  entry: NodeEntry,
250
  listStyleType: string
251
): void;
252
```
253

254
### toggleListByPathUnSet
255

256
Removes list formatting at a specific path.
257

258
```typescript { .api }
259
/**
260
 * Removes list formatting at a specific path
261
 * @param editor - The Slate editor instance
262
 * @param entry - The node entry to unformat
263
 */
264
function toggleListByPathUnSet(
265
  editor: SlateEditor,
266
  entry: NodeEntry
267
): void;
268
```
269

270
### toggleListSet
271

272
Sets list formatting if not already set, used internally by toggle operations.
273

274
```typescript { .api }
275
/**
276
 * Sets list formatting if not already set
277
 * @param editor - The Slate editor instance
278
 * @param entry - The node entry to format
279
 * @param options - Options for list configuration
280
 * @returns Boolean indicating if formatting was applied, undefined if no change
281
 */
282
function toggleListSet(
283
  editor: Editor,
284
  entry: NodeEntry,
285
  options: ListOptions
286
): boolean | undefined;
287
```
288

289
### toggleListUnset
290

291
Removes list formatting if already set, used internally by toggle operations.
292

293
```typescript { .api }
294
/**
295
 * Removes list formatting if already set
296
 * @param editor - The Slate editor instance
297
 * @param entry - The node entry to unformat
298
 * @param options - Options including list style type
299
 * @returns Boolean indicating if formatting was removed, undefined if no change
300
 */
301
function toggleListUnset(
302
  editor: Editor,
303
  entry: NodeEntry,
304
  options: { listStyleType?: string }
305
): boolean | undefined;
306
```
307

308
## Transform Options
309

310
### ListOptions
311

312
Comprehensive options for list transformation operations.
313

314
```typescript { .api }
315
/**
316
 * Options for list transformation operations
317
 */
318
interface ListOptions {
319
  /** Specific location to apply transform (defaults to selection) */
320
  at?: TLocation;
321
  /** Restart list numbering from this value */
322
  listRestart?: number;
323
  /** Politely restart list numbering (only at list start) */
324
  listRestartPolite?: number;
325
  /** List style type to apply */
326
  listStyleType?: ListStyleType | string;
327
}
328
```
329

330
## Common Transform Patterns
331

332
### Basic List Operations
333

334
```typescript
335
import { toggleList, indentList, outdentList, ListStyleType } from "@udecode/plate-list";
336

337
// Create bullet list
338
toggleList(editor, { listStyleType: ListStyleType.Disc });
339

340
// Create numbered list
341
toggleList(editor, { listStyleType: ListStyleType.Decimal });
342

343
// Increase indentation
344
indentList(editor);
345

346
// Decrease indentation
347
outdentList(editor);
348
```
349

350
### Advanced List Manipulation
351

352
```typescript
353
import { 
354
  toggleList, 
355
  setListNodes, 
356
  setListSiblingNodes,
357
  ListStyleType 
358
} from "@udecode/plate-list";
359

360
// Apply consistent formatting to multiple nodes
361
const entries = Array.from(Editor.nodes(editor, {
362
  match: n => Element.isElement(n)
363
}));
364

365
setListNodes(editor, entries, {
366
  listStyleType: ListStyleType.Decimal
367
});
368

369
// Restart numbering at 10
370
toggleList(editor, {
371
  listStyleType: ListStyleType.Decimal,
372
  listRestart: 10
373
});
374
```
375

376
### Todo List Operations
377

378
```typescript
379
import { indentTodo, toggleList, ListStyleType } from "@udecode/plate-list";
380

381
// Convert to todo list
382
indentTodo(editor);
383

384
// Or use toggleList for todo formatting
385
toggleList(editor, {
386
  listStyleType: ListStyleType.Disc, // Style for todo items
387
});
388
```
389

390
### Working with List Hierarchies
391

392
```typescript
393
import { 
394
  indentList, 
395
  outdentList, 
396
  getSiblingListStyleType,
397
  getListAbove 
398
} from "@udecode/plate-list";
399

400
// Smart indentation that matches sibling style
401
const currentList = getListAbove(editor);
402
if (currentList) {
403
  const siblingStyle = getSiblingListStyleType(editor, {
404
    entry: currentList,
405
    indent: 2, // Target indent level
406
    previous: true
407
  });
408
  
409
  indentList(editor, {
410
    listStyleType: siblingStyle
411
  });
412
}
413
```
414

415
## List Restart Features
416

417
### Immediate Restart
418

419
Forces list numbering to restart immediately:
420

421
```typescript
422
toggleList(editor, {
423
  listStyleType: ListStyleType.Decimal,
424
  listRestart: 1 // Force restart at 1
425
});
426
```
427

428
### Polite Restart
429

430
Only restarts numbering if at the beginning of a list sequence:
431

432
```typescript
433
toggleList(editor, {
434
  listStyleType: ListStyleType.Decimal,
435
  listRestartPolite: 1 // Only restart if at list start
436
});
437
```