0
# List Queries
1

2
Functions for finding and analyzing list structures, sibling relationships, and list properties.
3

4
## Capabilities
5

6
### someList
7

8
Checks if any node in the current selection matches the specified list type(s).
9

10
```typescript { .api }
11
/**
12
 * Checks if any node in selection matches the list type
13
 * @param editor - The Slate editor instance
14
 * @param type - List style type(s) to check for
15
 * @returns True if any selected node has matching list type
16
 */
17
function someList(editor: SlateEditor, type: string[] | string): boolean;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { someList, ListStyleType } from "@udecode/plate-list";
24

25
// Check for bullet lists
26
const hasBulletList = someList(editor, ListStyleType.Disc);
27

28
// Check for multiple list types
29
const hasNumberedLists = someList(editor, [
30
  ListStyleType.Decimal,
31
  ListStyleType.UpperRoman,
32
  ListStyleType.LowerRoman
33
]);
34
```
35

36
### someTodoList
37

38
Checks if any node in the current selection is a todo list.
39

40
```typescript { .api }
41
/**
42
 * Checks if any node in selection is a todo list
43
 * @param editor - The Slate editor instance
44
 * @returns True if any selected node is a todo list
45
 */
46
function someTodoList(editor: SlateEditor): boolean;
47
```
48

49
### getListAbove
50

51
Gets the list node above the current selection.
52

53
```typescript { .api }
54
/**
55
 * Gets the list node above the current selection
56
 * @param editor - The Slate editor instance
57
 * @param options - Query options (excluding match)
58
 * @returns The list node entry or undefined if not found
59
 */
60
function getListAbove<N extends ElementOf<E>, E extends Editor = Editor>(
61
  editor: E,
62
  options?: Omit<EditorAboveOptions, 'match'>
63
): NodeEntry<N> | undefined;
64
```
65

66
**Usage Example:**
67

68
```typescript
69
import { getListAbove } from "@udecode/plate-list";
70

71
// Get the current list item
72
const listItem = getListAbove(editor);
73
if (listItem) {
74
  const [node, path] = listItem;
75
  console.log('Current list item:', node);
76
}
77
```
78

79
### getListSiblings
80

81
Gets all sibling list nodes (previous, current, next) relative to the given entry.
82

83
```typescript { .api }
84
/**
85
 * Gets all sibling list nodes (previous, current, next)
86
 * @param editor - The Slate editor instance
87
 * @param entry - The reference list entry
88
 * @param options - Options for sibling retrieval
89
 * @returns Array of sibling list node entries
90
 */
91
function getListSiblings<N extends ElementOf<E>, E extends Editor = Editor>(
92
  editor: E,
93
  entry: ElementEntryOf<E>,
94
  options: GetListSiblingsOptions<N, E> = {}
95
): NodeEntry<N>[];
96
```
97

98
**Usage Example:**
99

100
```typescript
101
import { getListSiblings, getListAbove } from "@udecode/plate-list";
102

103
const currentList = getListAbove(editor);
104
if (currentList) {
105
  // Get all siblings including current
106
  const siblings = getListSiblings(editor, currentList, {
107
    current: true,
108
    next: true,
109
    previous: true
110
  });
111
  
112
  // Get only previous siblings
113
  const previousSiblings = getListSiblings(editor, currentList, {
114
    previous: true
115
  });
116
}
117
```
118

119
### getNextList
120

121
Gets the next list node relative to the given entry.
122

123
```typescript { .api }
124
/**
125
 * Gets the next list node
126
 * @param editor - The Slate editor instance
127
 * @param entry - The reference list entry
128
 * @param options - Options for sibling list queries
129
 * @returns The next list node entry or undefined
130
 */
131
function getNextList<N extends ElementOf<E>, E extends Editor = Editor>(
132
  editor: E,
133
  entry: ElementEntryOf<E>,
134
  options?: Partial<GetSiblingListOptions<N, E>>
135
): NodeEntry<N> | undefined;
136
```
137

138
### getPreviousList
139

140
Gets the previous list node relative to the given entry.
141

142
```typescript { .api }
143
/**
144
 * Gets the previous list node
145
 * @param editor - The Slate editor instance
146
 * @param entry - The reference list entry
147
 * @param options - Options for sibling list queries
148
 * @returns The previous list node entry or undefined
149
 */
150
function getPreviousList<N extends ElementOf<E>, E extends Editor = Editor>(
151
  editor: E,
152
  entry: ElementEntryOf<E>,
153
  options?: Partial<GetSiblingListOptions<N, E>>
154
): NodeEntry<N> | undefined;
155
```
156

157
### getSiblingList
158

159
Gets the next sibling list node with matching listStyleType.
160

161
```typescript { .api }
162
/**
163
 * Gets the next sibling list node with matching listStyleType
164
 * @param editor - The Slate editor instance
165
 * @param entry - The reference list entry
166
 * @param options - Options for sibling list matching
167
 * @returns The matching sibling list node entry or undefined
168
 */
169
function getSiblingList<N extends ElementOf<E>, E extends Editor = Editor>(
170
  editor: E,
171
  entry: ElementEntryOf<E>,
172
  options: GetSiblingListOptions<N, E>
173
): NodeEntry<N> | undefined;
174
```
175

176
### getSiblingListStyleType
177

178
Gets the first sibling list style type at the given indent level.
179

180
```typescript { .api }
181
/**
182
 * Gets the first sibling list style type at the given indent
183
 * @param editor - The Slate editor instance
184
 * @param options - Options including entry, indent level, and sibling options
185
 * @returns The sibling list style type
186
 */
187
function getSiblingListStyleType<E extends SlateEditor>(
188
  editor: E,
189
  options: {
190
    entry: NodeEntry<TElement>;
191
    indent: number;
192
  } & GetListSiblingsOptions<ElementOf<E>, E>
193
): ListStyleType;
194
```
195

196
**Usage Example:**
197

198
```typescript
199
import { getSiblingListStyleType, getListAbove } from "@udecode/plate-list";
200

201
const currentList = getListAbove(editor);
202
if (currentList) {
203
  // Get the list style type that siblings at indent level 2 should use
204
  const siblingStyleType = getSiblingListStyleType(editor, {
205
    entry: currentList,
206
    indent: 2,
207
    previous: true
208
  });
209
}
210
```
211

212
### areEqListStyleType
213

214
Checks if all entries have the same list style type.
215

216
```typescript { .api }
217
/**
218
 * Checks if all entries have the same list style type
219
 * @param editor - The Slate editor instance
220
 * @param entries - Array of node entries to check
221
 * @param options - Options including the expected list style type
222
 * @returns True if all entries have matching list style type
223
 */
224
function areEqListStyleType(
225
  editor: Editor,
226
  entries: NodeEntry[],
227
  options: { listStyleType?: string }
228
): boolean;
229
```
230

231
### isOrderedList
232

233
Determines if an element is an ordered list (numbered) or unordered list (bulleted).
234

235
```typescript { .api }
236
/**
237
 * Determines if an element is an ordered list
238
 * @param element - The element to check
239
 * @returns True if the element is an ordered list
240
 */
241
function isOrderedList(element: TElement): boolean;
242
```
243

244
**Usage Example:**
245

246
```typescript
247
import { isOrderedList, getListAbove } from "@udecode/plate-list";
248

249
const currentList = getListAbove(editor);
250
if (currentList) {
251
  const [node] = currentList;
252
  if (isOrderedList(node)) {
253
    console.log('This is a numbered list');
254
  } else {
255
    console.log('This is a bulleted list');
256
  }
257
}
258
```
259

260
## Query Options
261

262
### GetListSiblingsOptions
263

264
Options for getting multiple list siblings with fine-grained control.
265

266
```typescript { .api }
267
/**
268
 * Options for getting multiple list siblings
269
 */
270
interface GetListSiblingsOptions<N extends ElementOf<E>, E extends Editor = Editor> 
271
  extends Partial<GetSiblingListOptions<N, E>> {
272
  /** Include current entry in results */
273
  current?: boolean;
274
  /** Include next siblings in results */
275
  next?: boolean;
276
  /** Include previous siblings in results */
277
  previous?: boolean;
278
}
279
```
280

281
### GetSiblingListOptions
282

283
Comprehensive options for sibling list queries with breaking conditions and custom logic.
284

285
```typescript { .api }
286
/**
287
 * Options for sibling list queries
288
 */
289
interface GetSiblingListOptions<N extends ElementOf<E>, E extends Editor = Editor> {
290
  /** Break on equal indent with different list style type */
291
  breakOnEqIndentNeqListStyleType?: boolean;
292
  /** Break when encountering list restart markers */
293
  breakOnListRestart?: boolean;
294
  /** Break when encountering lower indentation levels */
295
  breakOnLowerIndent?: boolean;
296
  /** Custom break condition function */
297
  breakQuery?: (siblingNode: TNode, currentNode: TNode) => boolean | undefined;
298
  /** Custom function to get next entry */
299
  getNextEntry?: (entry: NodeEntry<ElementOrTextOf<E>>) => NodeEntry<N> | undefined;
300
  /** Custom function to get previous entry */
301
  getPreviousEntry?: (entry: NodeEntry<ElementOrTextOf<E>>) => NodeEntry<N> | undefined;
302
  /** Only get siblings with equal indentation */
303
  eqIndent?: boolean;
304
  /** Custom query function for sibling matching */
305
  query?: (siblingNode: TNode, currentNode: TNode) => boolean | undefined;
306
}
307
```
308

309
## Common Query Patterns
310

311
### Finding List Context
312

313
```typescript
314
// Get current list item and its siblings
315
const currentList = getListAbove(editor);
316
if (currentList) {
317
  const siblings = getListSiblings(editor, currentList, {
318
    current: true,
319
    next: true,
320
    previous: true
321
  });
322
  
323
  const nextList = getNextList(editor, currentList);
324
  const prevList = getPreviousList(editor, currentList);
325
}
326
```
327

328
### Checking List Types
329

330
```typescript
331
// Check what types of lists are selected
332
const hasAnyList = someList(editor, Object.values(ListStyleType));
333
const hasBulletList = someList(editor, ListStyleType.Disc);
334
const hasTodoList = someTodoList(editor);
335

336
// Check consistency across multiple entries
337
const entries = Array.from(Editor.nodes(editor, { match: n => n.listStyleType }));
338
const allSameType = areEqListStyleType(editor, entries, {
339
  listStyleType: ListStyleType.Decimal
340
});
341
```