0
# Plate List Plugin
1

2
Plate List Plugin provides comprehensive list functionality for the Plate rich-text editor. It implements an indent-based "flat list" system where list structures have no nested children but use indentation levels to create hierarchy. The plugin supports 59 different list style types, comprehensive list manipulation transforms, query functions, and React hooks for UI integration.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  BaseListPlugin, 
16
  ListStyleType, 
17
  toggleList, 
18
  someList, 
19
  indentList, 
20
  outdentList,
21
  indentTodo,
22
  withList,
23
  getListAbove
24
} from "@udecode/plate-list";
25
```
26

27
For React-specific features:
28

29
```typescript
30
import { 
31
  ListPlugin, 
32
  useListToolbarButton, 
33
  useListToolbarButtonState,
34
  useTodoListElement,
35
  useTodoListElementState,
36
  useIndentTodoToolBarButton,
37
  useIndentTodoToolBarButtonState
38
} from "@udecode/plate-list/react";
39
```
40

41
CommonJS:
42

43
```javascript
44
const { BaseListPlugin, ListStyleType, toggleList } = require("@udecode/plate-list");
45
```
46

47
## Basic Usage
48

49
```typescript
50
import { createPlateEditor } from "@udecode/plate";
51
import { BaseListPlugin, ListStyleType, toggleList } from "@udecode/plate-list";
52

53
// Add list plugin to editor
54
const editor = createPlateEditor({
55
  plugins: [BaseListPlugin],
56
});
57

58
// Toggle bullet list on selected blocks
59
toggleList(editor, {
60
  listStyleType: ListStyleType.Disc,
61
});
62

63
// Toggle numbered list
64
toggleList(editor, {
65
  listStyleType: ListStyleType.Decimal,
66
});
67

68
// Check if selection contains lists
69
const hasLists = someList(editor, ListStyleType.Disc);
70
```
71

72
## Architecture
73

74
The Plate List Plugin is built around several key components:
75

76
- **Plugin System**: `BaseListPlugin` for core functionality, `ListPlugin` for React integration
77
- **Transform Operations**: Functions for indenting, outdenting, and toggling list formatting
78
- **Query System**: Functions for finding and analyzing list structures and relationships
79
- **Type System**: Comprehensive enum with 59 list style types supporting international numbering
80
- **React Integration**: Hooks for building list toolbar buttons and todo list components
81
- **Normalization Engine**: Automatic maintenance of consistent list structure and numbering
82

83
## Capabilities
84

85
### Plugin Configuration
86

87
Core plugin setup and configuration options for integrating list functionality into Plate editor.
88

89
```typescript { .api }
90
export const BaseListPlugin: TSlatePlugin<BaseListConfig>;
91
export const ListPlugin: PlatePlugin<ListConfig>; // React version
92

93
export type BaseListConfig = PluginConfig<
94
  'list',
95
  {
96
    getSiblingListOptions?: GetSiblingListOptions<TElement>;
97
    getListStyleType?: (element: HTMLElement) => ListStyleType;
98
  }
99
>;
100
```
101

102
[Plugin Configuration](./plugins.md)
103

104
### List Queries
105

106
Functions for finding and analyzing list structures, sibling relationships, and list properties.
107

108
```typescript { .api }
109
function someList(editor: SlateEditor, type: string[] | string): boolean;
110
function getListAbove<N extends ElementOf<E>, E extends Editor = Editor>(
111
  editor: E,
112
  options?: Omit<EditorAboveOptions, 'match'>
113
): NodeEntry<N> | undefined;
114
function getListSiblings<N extends ElementOf<E>, E extends Editor = Editor>(
115
  editor: E,
116
  entry: ElementEntryOf<E>,
117
  options: GetListSiblingsOptions<N, E>
118
): NodeEntry[];
119
```
120

121
[List Queries](./queries.md)
122

123
### List Transforms
124

125
Transform operations for manipulating list formatting, indentation, and structure.
126

127
```typescript { .api }
128
function toggleList<N extends ElementOf<E>, E extends SlateEditor = SlateEditor>(
129
  editor: E,
130
  options: ListOptions,
131
  getSiblingListOptions?: GetSiblingListOptions<N, E>
132
): void;
133
function indentList(editor: SlateEditor, options: ListOptions): void;
134
function outdentList(editor: SlateEditor, options: ListOptions): void;
135
```
136

137
[List Transforms](./transforms.md)
138

139
### React Hooks
140

141
React hooks for building list UI components and toolbar buttons.
142

143
```typescript { .api }
144
function useListToolbarButton(
145
  state: ReturnType<typeof useListToolbarButtonState>
146
): {
147
  props: {
148
    pressed: boolean;
149
    onClick: () => void;
150
    onMouseDown: (e: React.MouseEvent<HTMLButtonElement>) => void;
151
  };
152
};
153
function useTodoListElement(
154
  state: ReturnType<typeof useTodoListElementState>
155
): {
156
  checkboxProps: {
157
    checked: boolean;
158
    onCheckedChange: (value: boolean) => void;
159
    onMouseDown: (e: any) => void;
160
  };
161
};
162
function useIndentTodoToolBarButton(
163
  state: ReturnType<typeof useIndentTodoToolBarButtonState>
164
): {
165
  props: {
166
    pressed: boolean;
167
    onClick: () => void;
168
    onMouseDown: (e: React.MouseEvent<HTMLButtonElement>) => void;
169
  };
170
};
171
```
172

173
[React Hooks](./react-hooks.md)
174

175
### List Normalizers
176

177
Automatic maintenance functions that ensure consistent list structure and numbering.
178

179
```typescript { .api }
180
function normalizeListStart<N extends ElementOf<E>, E extends Editor = Editor>(
181
  editor: E,
182
  entry: ElementEntryOf<E>,
183
  options?: Partial<GetSiblingListOptions<N, E>>
184
): boolean;
185
function normalizeListNotIndented(editor: Editor, entry: NodeEntry): boolean;
186
function withInsertBreakList(context: EditorContext): OverrideTransforms;
187
```
188

189
[List Normalizers](./normalizers.md)
190

191
### Types and Constants
192

193
Type definitions, enums, and constants including the comprehensive ListStyleType enum with 59 international list style values.
194

195
```typescript { .api }
196
enum ListStyleType {
197
  Disc = 'disc',
198
  Circle = 'circle',
199
  Square = 'square',
200
  Decimal = 'decimal',
201
  UpperRoman = 'upper-roman',
202
  LowerRoman = 'lower-roman',
203
  // ... 53 more values including international numbering systems
204
}
205

206
interface ListOptions {
207
  at?: TLocation;
208
  listRestart?: number;
209
  listRestartPolite?: number;
210
  listStyleType?: ListStyleType | string;
211
}
212
```
213

214
[Types and Constants](./types.md)