0
# React Hooks
1

2
React hooks for building list UI components and toolbar buttons. These hooks provide the state management and event handling needed for list-related UI components.
3

4
## Capabilities
5

6
### useListToolbarButtonState
7

8
State hook for list toolbar button that tracks whether the current selection contains lists of a specific type.
9

10
```typescript { .api }
11
/**
12
 * State hook for list toolbar button
13
 * @param options - Configuration including node type
14
 * @returns State object with nodeType and pressed status
15
 */
16
function useListToolbarButtonState(options?: {
17
  nodeType?: string;
18
}): {
19
  nodeType: string;
20
  pressed: boolean;
21
};
22
```
23

24
**Usage Example:**
25

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

29
function BulletListButton() {
30
  const state = useListToolbarButtonState({
31
    nodeType: ListStyleType.Disc
32
  });
33
  
34
  // state.pressed will be true if selection contains bullet lists
35
  return <button className={state.pressed ? 'active' : ''}>{/* ... */}</button>;
36
}
37
```
38

39
### useListToolbarButton
40

41
Behavior hook for list toolbar button that provides click handlers and props for toggling list formatting.
42

43
```typescript { .api }
44
/**
45
 * Behavior hook for list toolbar button
46
 * @param state - State from useListToolbarButtonState
47
 * @returns Props object with event handlers
48
 */
49
function useListToolbarButton(
50
  state: ReturnType<typeof useListToolbarButtonState>
51
): {
52
  props: {
53
    pressed: boolean;
54
    onClick: () => void;
55
    onMouseDown: (e: React.MouseEvent<HTMLButtonElement>) => void;
56
  };
57
};
58
```
59

60
**Complete Usage Example:**
61

62
```typescript
63
import { 
64
  useListToolbarButtonState, 
65
  useListToolbarButton,
66
  ListStyleType 
67
} from "@udecode/plate-list/react";
68

69
function BulletListToolbarButton() {
70
  const state = useListToolbarButtonState({
71
    nodeType: ListStyleType.Disc
72
  });
73
  const { props } = useListToolbarButton(state);
74
  
75
  return (
76
    <button {...props}>
77
      Bullet List
78
    </button>
79
  );
80
}
81

82
function NumberedListToolbarButton() {
83
  const state = useListToolbarButtonState({
84
    nodeType: ListStyleType.Decimal
85
  });
86
  const { props } = useListToolbarButton(state);
87
  
88
  return (
89
    <button {...props}>
90
      Numbered List
91
    </button>
92
  );
93
}
94
```
95

96
### useTodoListElementState
97

98
State hook for todo list element that manages checkbox state and editor context.
99

100
```typescript { .api }
101
/**
102
 * State hook for todo list element
103
 * @param options - Configuration including element
104
 * @returns State object with checkbox status and editor context
105
 */
106
function useTodoListElementState(options: {
107
  element: TElement;
108
}): {
109
  checked: boolean;
110
  editor: PlateEditor;
111
  element: TElement;
112
  readOnly: boolean;
113
};
114
```
115

116
### useTodoListElement
117

118
Behavior hook for todo list element that provides checkbox props and change handlers.
119

120
```typescript { .api }
121
/**
122
 * Behavior hook for todo list element
123
 * @param state - State from useTodoListElementState
124
 * @returns Checkbox props object with event handlers
125
 */
126
function useTodoListElement(
127
  state: ReturnType<typeof useTodoListElementState>
128
): {
129
  checkboxProps: {
130
    checked: boolean;
131
    onCheckedChange: (value: boolean) => void;
132
    onMouseDown: (e: any) => void;
133
  };
134
};
135
```
136

137
**Complete Usage Example:**
138

139
```typescript
140
import {
141
  useTodoListElementState,
142
  useTodoListElement
143
} from "@udecode/plate-list/react";
144
import { PlateRenderElementProps } from "@udecode/plate/react";
145

146
function TodoListElement({ element, children }: PlateRenderElementProps) {
147
  const state = useTodoListElementState({ element });
148
  const { checkboxProps } = useTodoListElement(state);
149
  
150
  return (
151
    <div className="todo-list-item">
152
      <input
153
        type="checkbox"
154
        {...checkboxProps}
155
      />
156
      <span className={checkboxProps.checked ? 'completed' : ''}>
157
        {children}
158
      </span>
159
    </div>
160
  );
161
}
162
```
163

164
### useIndentTodoToolBarButtonState
165

166
State hook for todo list toolbar button that tracks todo list presence in selection.
167

168
```typescript { .api }
169
/**
170
 * State hook for todo list toolbar button
171
 * @param options - Configuration including node type
172
 * @returns State object with nodeType and pressed status
173
 */
174
function useIndentTodoToolBarButtonState(options?: {
175
  nodeType?: string;
176
}): {
177
  nodeType: string;
178
  pressed: boolean;
179
};
180
```
181

182
### useIndentTodoToolBarButton
183

184
Behavior hook for todo list toolbar button that provides click handlers for toggling todo list formatting.
185

186
```typescript { .api }
187
/**
188
 * Behavior hook for todo list toolbar button
189
 * @param state - State from useIndentTodoToolBarButtonState
190
 * @returns Props object with event handlers
191
 */
192
function useIndentTodoToolBarButton(
193
  state: ReturnType<typeof useIndentTodoToolBarButtonState>
194
): {
195
  props: {
196
    pressed: boolean;
197
    onClick: () => void;
198
    onMouseDown: (e: React.MouseEvent<HTMLButtonElement>) => void;
199
  };
200
};
201
```
202

203
**Usage Example:**
204

205
```typescript
206
import {
207
  useIndentTodoToolBarButtonState,
208
  useIndentTodoToolBarButton,
209
  ListStyleType
210
} from "@udecode/plate-list/react";
211

212
function TodoListToolbarButton() {
213
  const state = useIndentTodoToolBarButtonState({
214
    nodeType: ListStyleType.Disc
215
  });
216
  const { props } = useIndentTodoToolBarButton(state);
217
  
218
  return (
219
    <button {...props}>
220
      Todo List
221
    </button>
222
  );
223
}
224
```
225

226
## Hook Patterns
227

228
### Building Complete Toolbar
229

230
```typescript
231
import {
232
  useListToolbarButtonState,
233
  useListToolbarButton,
234
  useIndentTodoToolBarButtonState,
235
  useIndentTodoToolBarButton,
236
  ListStyleType
237
} from "@udecode/plate-list/react";
238

239
function ListToolbar() {
240
  // Bullet list button
241
  const bulletState = useListToolbarButtonState({
242
    nodeType: ListStyleType.Disc
243
  });
244
  const { props: bulletProps } = useListToolbarButton(bulletState);
245
  
246
  // Numbered list button
247
  const numberedState = useListToolbarButtonState({
248
    nodeType: ListStyleType.Decimal
249
  });
250
  const { props: numberedProps } = useListToolbarButton(numberedState);
251
  
252
  // Todo list button
253
  const todoState = useIndentTodoToolBarButtonState();
254
  const { props: todoProps } = useIndentTodoToolBarButton(todoState);
255
  
256
  return (
257
    <div className="list-toolbar">
258
      <button {...bulletProps}>• Bullets</button>
259
      <button {...numberedProps}>1. Numbers</button>
260
      <button {...todoProps}>☐ Todo</button>
261
    </div>
262
  );
263
}
264
```
265

266
### Building Custom List Components
267

268
```typescript
269
import { 
270
  useTodoListElementState,
271
  useTodoListElement
272
} from "@udecode/plate-list/react";
273
import { PlateRenderElementProps } from "@udecode/plate/react";
274

275
function CustomTodoListElement({ element, children }: PlateRenderElementProps) {
276
  const state = useTodoListElementState({ element });
277
  const { checkboxProps } = useTodoListElement(state);
278
  
279
  return (
280
    <div className={`todo-item ${state.readOnly ? 'readonly' : ''}`}>
281
      <label className="todo-checkbox-container">
282
        <input
283
          type="checkbox"
284
          className="todo-checkbox"
285
          {...checkboxProps}
286
          disabled={state.readOnly}
287
        />
288
        <span className="checkmark"></span>
289
      </label>
290
      <div className={`todo-content ${checkboxProps.checked ? 'completed' : ''}`}>
291
        {children}
292
      </div>
293
    </div>
294
  );
295
}
296
```
297

298
### Conditional Rendering Based on List State
299

300
```typescript
301
import { useListToolbarButtonState, ListStyleType } from "@udecode/plate-list/react";
302

303
function SmartListControls() {
304
  const bulletState = useListToolbarButtonState({
305
    nodeType: ListStyleType.Disc
306
  });
307
  const numberedState = useListToolbarButtonState({
308
    nodeType: ListStyleType.Decimal
309
  });
310
  
311
  const hasAnyList = bulletState.pressed || numberedState.pressed;
312
  
313
  return (
314
    <div>
315
      {/* Always show list creation buttons */}
316
      <ListCreationButtons />
317
      
318
      {/* Only show indentation controls when in a list */}
319
      {hasAnyList && <IndentationControls />}
320
    </div>
321
  );
322
}
323
```
324

325
## State Management
326

327
### Hook State Flow
328

329
1. **State Hooks** (`useListToolbarButtonState`, `useTodoListElementState`) query the editor and return current state
330
2. **Behavior Hooks** (`useListToolbarButton`, `useTodoListElement`) provide event handlers that modify editor state
331
3. **State changes** trigger re-renders with updated state from state hooks
332

333
### Editor Integration
334

335
All hooks integrate with the Plate editor through:
336
- `useEditorRef()` - Gets current editor instance
337
- `useEditorSelector()` - Subscribes to editor state changes
338
- `useReadOnly()` - Respects editor read-only state
339

340
### Performance Considerations
341

342
- State hooks use `useEditorSelector` for efficient re-rendering
343
- Only re-render when relevant editor state changes
344
- Event handlers are memoized to prevent unnecessary re-renders