0
# Structure Controls
1

2
Controls for document structure including headings, lists, blockquotes, alignment options, and task management. These controls help organize content hierarchy and layout.
3

4
## Capabilities
5

6
### Heading Controls
7

8
Six heading levels for creating document hierarchy and structure.
9

10
```typescript { .api }
11
/**
12
 * Heading level 1 control - largest heading
13
 * Keyboard shortcut: Ctrl/Cmd + Alt + 1
14
 */
15
RichTextEditor.H1: React.ComponentType;
16

17
/**
18
 * Heading level 2 control 
19
 * Keyboard shortcut: Ctrl/Cmd + Alt + 2
20
 */
21
RichTextEditor.H2: React.ComponentType;
22

23
/**
24
 * Heading level 3 control
25
 * Keyboard shortcut: Ctrl/Cmd + Alt + 3  
26
 */
27
RichTextEditor.H3: React.ComponentType;
28

29
/**
30
 * Heading level 4 control
31
 * Keyboard shortcut: Ctrl/Cmd + Alt + 4
32
 */
33
RichTextEditor.H4: React.ComponentType;
34

35
/**
36
 * Heading level 5 control
37
 * Keyboard shortcut: Ctrl/Cmd + Alt + 5
38
 */
39
RichTextEditor.H5: React.ComponentType;
40

41
/**
42
 * Heading level 6 control - smallest heading
43
 * Keyboard shortcut: Ctrl/Cmd + Alt + 6
44
 */
45
RichTextEditor.H6: React.ComponentType;
46
```
47

48
**Usage Example:**
49

50
```typescript
51
<RichTextEditor.ControlsGroup>
52
  <RichTextEditor.H1 />
53
  <RichTextEditor.H2 />
54
  <RichTextEditor.H3 />
55
  <RichTextEditor.H4 />
56
  <RichTextEditor.H5 />
57
  <RichTextEditor.H6 />
58
</RichTextEditor.ControlsGroup>
59
```
60

61
### List Controls
62

63
Controls for creating and managing different types of lists.
64

65
```typescript { .api }
66
/**
67
 * Bullet list control - creates unordered lists
68
 * Keyboard shortcut: Ctrl/Cmd + Shift + 8
69
 */
70
RichTextEditor.BulletList: React.ComponentType;
71

72
/**
73
 * Ordered list control - creates numbered lists  
74
 * Keyboard shortcut: Ctrl/Cmd + Shift + 7
75
 */
76
RichTextEditor.OrderedList: React.ComponentType;
77

78
/**
79
 * Task list control - creates interactive checkboxes
80
 * Keyboard shortcut: Ctrl/Cmd + Shift + 9
81
 */
82
RichTextEditor.TaskList: React.ComponentType;
83
```
84

85
**Usage Example:**
86

87
```typescript
88
<RichTextEditor.ControlsGroup>
89
  <RichTextEditor.BulletList />
90
  <RichTextEditor.OrderedList />
91
  <RichTextEditor.TaskList />
92
</RichTextEditor.ControlsGroup>
93
```
94

95
### Task List Management Controls
96

97
Controls for managing task list hierarchy and indentation.
98

99
```typescript { .api }
100
/**
101
 * Task list sink control - increases task indentation level
102
 * Keyboard shortcut: Ctrl/Cmd + ]
103
 */
104
RichTextEditor.TaskListSink: React.ComponentType;
105

106
/**
107
 * Task list lift control - decreases task indentation level  
108
 * Keyboard shortcut: Ctrl/Cmd + [
109
 */
110
RichTextEditor.TaskListLift: React.ComponentType;
111
```
112

113
**Usage Example:**
114

115
```typescript
116
<RichTextEditor.ControlsGroup>
117
  <RichTextEditor.TaskList />
118
  <RichTextEditor.TaskListSink />
119
  <RichTextEditor.TaskListLift />
120
</RichTextEditor.ControlsGroup>
121
```
122

123
### Alignment Controls
124

125
Controls for text alignment and justification.
126

127
```typescript { .api }
128
/**
129
 * Left align control - aligns text to the left
130
 */
131
RichTextEditor.AlignLeft: React.ComponentType;
132

133
/**
134
 * Center align control - centers text horizontally
135
 */
136
RichTextEditor.AlignCenter: React.ComponentType;
137

138
/**
139
 * Right align control - aligns text to the right
140
 */
141
RichTextEditor.AlignRight: React.ComponentType;
142

143
/**
144
 * Justify align control - justifies text to fill line width
145
 */
146
RichTextEditor.AlignJustify: React.ComponentType;
147
```
148

149
**Usage Example:**
150

151
```typescript
152
<RichTextEditor.ControlsGroup>
153
  <RichTextEditor.AlignLeft />
154
  <RichTextEditor.AlignCenter />
155
  <RichTextEditor.AlignRight />
156
  <RichTextEditor.AlignJustify />
157
</RichTextEditor.ControlsGroup>
158
```
159

160
### Blockquote Control
161

162
Control for creating quoted text blocks.
163

164
```typescript { .api }
165
/**
166
 * Blockquote control - creates indented quote blocks
167
 * Keyboard shortcut: Ctrl/Cmd + Shift + B
168
 */
169
RichTextEditor.Blockquote: React.ComponentType;
170
```
171

172
**Usage Example:**
173

174
```typescript
175
<RichTextEditor.ControlsGroup>
176
  <RichTextEditor.Blockquote />
177
</RichTextEditor.ControlsGroup>
178
```
179

180
## Complete Structure Example
181

182
```typescript
183
import { useEditor } from "@tiptap/react";
184
import StarterKit from "@tiptap/starter-kit";
185
import TaskList from "@tiptap/extension-task-list";
186
import TaskItem from "@tiptap/extension-task-item";
187
import TextAlign from "@tiptap/extension-text-align";
188
import { RichTextEditor, getTaskListExtension } from "@mantine/tiptap";
189

190
function StructuredEditor() {
191
  const editor = useEditor({
192
    extensions: [
193
      StarterKit,
194
      getTaskListExtension(TaskList),
195
      TaskItem.configure({
196
        nested: true,
197
      }),
198
      TextAlign.configure({ types: ['heading', 'paragraph'] }),
199
    ],
200
    content: `
201
      <h1>Document Title</h1>
202
      <p>This is a paragraph with some content.</p>
203
      <h2>Subsection</h2>
204
      <ul>
205
        <li>Bullet point 1</li>
206
        <li>Bullet point 2</li>
207
      </ul>
208
      <blockquote>This is a quoted section</blockquote>
209
    `,
210
  });
211

212
  return (
213
    <RichTextEditor editor={editor}>
214
      <RichTextEditor.Toolbar sticky stickyOffset={60}>
215
        {/* Heading controls */}
216
        <RichTextEditor.ControlsGroup>
217
          <RichTextEditor.H1 />
218
          <RichTextEditor.H2 />
219
          <RichTextEditor.H3 />
220
          <RichTextEditor.H4 />
221
        </RichTextEditor.ControlsGroup>
222

223
        {/* List controls */}
224
        <RichTextEditor.ControlsGroup>
225
          <RichTextEditor.BulletList />
226
          <RichTextEditor.OrderedList />
227
          <RichTextEditor.TaskList />
228
        </RichTextEditor.ControlsGroup>
229

230
        {/* Task management */}
231
        <RichTextEditor.ControlsGroup>
232
          <RichTextEditor.TaskListSink />
233
          <RichTextEditor.TaskListLift />
234
        </RichTextEditor.ControlsGroup>
235

236
        {/* Alignment controls */}
237
        <RichTextEditor.ControlsGroup>
238
          <RichTextEditor.AlignLeft />
239
          <RichTextEditor.AlignCenter />
240
          <RichTextEditor.AlignRight />
241
          <RichTextEditor.AlignJustify />
242
        </RichTextEditor.ControlsGroup>
243

244
        {/* Block formatting */}
245
        <RichTextEditor.ControlsGroup>
246
          <RichTextEditor.Blockquote />
247
        </RichTextEditor.ControlsGroup>
248
      </RichTextEditor.Toolbar>
249

250
      <RichTextEditor.Content />
251
    </RichTextEditor>
252
  );
253
}
254
```
255

256
## Control Behavior
257

258
### Active States
259

260
Structure controls show active states based on cursor position:
261

262
- **Headings**: Active when cursor is within a heading of that level
263
- **Lists**: Active when cursor is within that type of list
264
- **Blockquote**: Active when cursor is within a blockquote
265
- **Alignment**: Active based on current paragraph alignment
266

267
### List Behavior
268

269
- **Bullet/Ordered Lists**: Toggle between list and paragraph modes
270
- **Task Lists**: Create interactive checkboxes that can be checked/unchecked
271
- **Nesting**: Lists can be nested using Task List Sink/Lift controls
272

273
### Task List Features
274

275
Task lists created with `RichTextEditor.TaskList` support:
276

277
- **Interactive Checkboxes**: Click to toggle completion state
278
- **Keyboard Navigation**: Tab/Shift+Tab to navigate between tasks
279
- **Nesting**: Use Sink/Lift controls to create hierarchical task lists
280
- **Custom Styling**: Tasks can be styled based on completion state
281

282
## Required Extensions
283

284
Structure controls require specific Tiptap extensions:
285

286
- **Headings**: Included in `@tiptap/starter-kit`
287
- **Lists**: Included in `@tiptap/starter-kit` 
288
- **Task Lists**: Requires `@tiptap/extension-task-list` and `@tiptap/extension-task-item`
289
- **Alignment**: Requires `@tiptap/extension-text-align`
290
- **Blockquote**: Included in `@tiptap/starter-kit`
291

292
## Customization
293

294
### Custom Labels
295

296
```typescript
297
<RichTextEditor 
298
  editor={editor}
299
  labels={{
300
    h1ControlLabel: "Heading 1",
301
    h2ControlLabel: "Heading 2", 
302
    bulletListControlLabel: "Bullet List",
303
    orderedListControlLabel: "Numbered List",
304
    tasksControlLabel: "Task List",
305
    blockquoteControlLabel: "Quote Block",
306
    alignLeftControlLabel: "Align Left",
307
    alignCenterControlLabel: "Center Text",
308
    alignRightControlLabel: "Align Right",
309
    alignJustifyControlLabel: "Justify Text",
310
  }}
311
>
312
  {/* structure controls */}
313
</RichTextEditor>
314
```
315

316
### Task List Extension Configuration
317

318
```typescript
319
import TaskList from "@tiptap/extension-task-list";
320
import TaskItem from "@tiptap/extension-task-item";
321
import { getTaskListExtension } from "@mantine/tiptap";
322

323
const editor = useEditor({
324
  extensions: [
325
    // Enhanced task list with keyboard shortcuts and styling
326
    getTaskListExtension(TaskList),
327
    TaskItem.configure({
328
      nested: true,
329
      HTMLAttributes: {
330
        class: 'my-task-item',
331
      },
332
    }),
333
  ],
334
});
335
```