0
# Plugin Configuration
1

2
Core plugin setup and configuration options for integrating list functionality into Plate editor.
3

4
## Capabilities
5

6
### BaseListPlugin
7

8
Core list plugin that provides list functionality for Plate editor.
9

10
```typescript { .api }
11
/**
12
 * Core list plugin providing list functionality for Plate editor
13
 * Handles list rendering, normalization, and operation behaviors
14
 */
15
export const BaseListPlugin: TSlatePlugin<BaseListConfig>;
16
```
17

18
**Usage Example:**
19

20
```typescript
21
import { createPlateEditor } from "@udecode/plate";
22
import { BaseListPlugin } from "@udecode/plate-list";
23

24
const editor = createPlateEditor({
25
  plugins: [BaseListPlugin],
26
});
27
```
28

29
### ListPlugin (React)
30

31
React wrapper for BaseListPlugin with React-specific features.
32

33
```typescript { .api }
34
/**
35
 * React wrapper for BaseListPlugin with React-specific features
36
 * Enables support for indented lists with React-specific features
37
 */
38
export const ListPlugin: PlatePlugin<ListConfig>;
39
```
40

41
**Usage Example:**
42

43
```typescript
44
import { createPlateEditor } from "@udecode/plate/react";
45
import { ListPlugin } from "@udecode/plate-list/react";
46

47
const editor = createPlateEditor({
48
  plugins: [ListPlugin],
49
});
50
```
51

52
### BaseListConfig
53

54
Configuration options for the BaseListPlugin.
55

56
```typescript { .api }
57
/**
58
 * Configuration options for the BaseListPlugin
59
 */
60
export type BaseListConfig = PluginConfig<
61
  'list',
62
  {
63
    /** Options for getting sibling lists */
64
    getSiblingListOptions?: GetSiblingListOptions<TElement>;
65
    /** Function to map HTML elements to list style type */
66
    getListStyleType?: (element: HTMLElement) => ListStyleType;
67
  }
68
>;
69
```
70

71
### ListConfig
72

73
React version of BaseListConfig.
74

75
```typescript { .api }
76
/**
77
 * React version of BaseListConfig
78
 */
79
export type ListConfig = BaseListConfig;
80
```
81

82
### Configuration Options
83

84
#### getSiblingListOptions
85

86
Options for configuring how sibling list queries behave. This affects how the plugin finds and analyzes related list items.
87

88
```typescript { .api }
89
interface GetSiblingListOptions<N extends ElementOf<E>, E extends Editor = Editor> {
90
  /** Break on equal indent with different list style type */
91
  breakOnEqIndentNeqListStyleType?: boolean;
92
  /** Break when encountering list restart markers */
93
  breakOnListRestart?: boolean;
94
  /** Break when encountering lower indentation levels */
95
  breakOnLowerIndent?: boolean;
96
  /** Custom break condition function */
97
  breakQuery?: (siblingNode: TNode, currentNode: TNode) => boolean | undefined;
98
  /** Custom function to get next entry */
99
  getNextEntry?: (entry: NodeEntry<ElementOrTextOf<E>>) => NodeEntry<N> | undefined;
100
  /** Custom function to get previous entry */
101
  getPreviousEntry?: (entry: NodeEntry<ElementOrTextOf<E>>) => NodeEntry<N> | undefined;
102
  /** Only get siblings with equal indentation */
103
  eqIndent?: boolean;
104
  /** Custom query function for sibling matching */
105
  query?: (siblingNode: TNode, currentNode: TNode) => boolean | undefined;
106
}
107
```
108

109
#### getListStyleType
110

111
Function to map HTML elements to list style types during HTML parsing. This is used when importing content from external sources.
112

113
```typescript { .api }
114
/**
115
 * Function to map HTML elements to list style types during HTML parsing
116
 * @param element - HTML element to analyze
117
 * @returns The corresponding ListStyleType
118
 */
119
type GetListStyleTypeFunction = (element: HTMLElement) => ListStyleType;
120
```
121

122
**Default Implementation:**
123

124
```typescript
125
// Default implementation extracts from CSS list-style-type property
126
getListStyleType: (element) => element.style.listStyleType as ListStyleType
127
```
128

129
## Plugin Features
130

131
### HTML Parsing
132

133
The plugin includes built-in HTML parsing that:
134
- Transforms `<li>` elements into flat list items with indent properties
135
- Preserves list style types from CSS
136
- Handles nested HTML lists by converting to indentation-based structure
137
- Extracts `aria-level` attributes for accessibility compliance
138

139
### List Rendering
140

141
The plugin provides default rendering that:
142
- Renders list items as `<ol>` or `<ul>` elements based on list style type
143
- Maintains proper `start` attributes for numbered lists
144
- Applies CSS list-style-type properties
145
- Supports all 59 international list style types
146

147
### Editor Extensions
148

149
The plugin automatically applies editor extensions:
150
- `withList`: Core list functionality and transforms
151
- `withNormalizeList`: List structure normalization
152

153
### List Rules
154

155
The plugin defines specific editor rules:
156
- **Break behavior**: Empty list items reset to normal text
157
- **Delete behavior**: Deletion at list start resets formatting
158
- **Merge behavior**: Prevents removal of empty list items during merges
159
- **Match condition**: Identifies list nodes by presence of listType property