0
# Advanced Controls
1

2
Advanced formatting options including code blocks, color controls, links, special text features, and utility controls for enhanced text editing capabilities.
3

4
## Capabilities
5

6
### Code Controls
7

8
Controls for inline code and code block formatting.
9

10
```typescript { .api }
11
/**
12
 * Inline code control - formats selected text as inline code
13
 * Keyboard shortcut: Ctrl/Cmd + E
14
 */
15
RichTextEditor.Code: React.ComponentType;
16

17
/**
18
 * Code block control - creates formatted code blocks
19
 * Keyboard shortcut: Ctrl/Cmd + Alt + C
20
 */
21
RichTextEditor.CodeBlock: React.ComponentType;
22
```
23

24
**Usage Example:**
25

26
```typescript
27
<RichTextEditor.ControlsGroup>
28
  <RichTextEditor.Code />
29
  <RichTextEditor.CodeBlock />
30
</RichTextEditor.ControlsGroup>
31
```
32

33
### Color Controls
34

35
Controls for applying and managing text colors.
36

37
```typescript { .api }
38
/**
39
 * Color control - applies specific color to selected text
40
 * @param props - Color control configuration
41
 */
42
RichTextEditor.Color: React.ComponentType<RichTextEditorColorControlProps>;
43

44
interface RichTextEditorColorControlProps extends BoxProps, ElementProps<'button'> {
45
  /** Color that will be set as text color, for example #ef457e */
46
  color: string;
47
}
48

49
/**
50
 * Color picker control - provides color palette and custom color selection
51
 * @param props - Color picker configuration
52
 */
53
RichTextEditor.ColorPicker: React.ComponentType<RichTextEditorColorPickerControlProps>;
54

55
interface RichTextEditorColorPickerControlProps extends BoxProps, ElementProps<'button'> {
56
  /** Props added to Popover component */
57
  popoverProps?: Partial<PopoverProps>;
58
  /** Props added to ColorPicker component */
59
  colorPickerProps?: Partial<ColorPickerProps>;
60
  /** List of colors that the user can choose from */
61
  colors: string[];
62
}
63

64
/**
65
 * Highlight control - applies background highlight to selected text
66
 */
67
RichTextEditor.Highlight: React.ComponentType;
68

69
/**
70
 * Unset color control - removes text color formatting
71
 */
72
RichTextEditor.UnsetColor: React.ComponentType;
73
```
74

75
**Usage Example:**
76

77
```typescript
78
<RichTextEditor.ControlsGroup>
79
  <RichTextEditor.ColorPicker colors={['#ff0000', '#00ff00', '#0000ff']} />
80
  <RichTextEditor.Color color="#ff6b6b" />
81
  <RichTextEditor.Color color="#51cf66" />
82
  <RichTextEditor.Color color="#339af0" />
83
  <RichTextEditor.Highlight />
84
  <RichTextEditor.UnsetColor />
85
</RichTextEditor.ControlsGroup>
86
```
87

88
### Link Controls
89

90
Controls for creating and managing hyperlinks.
91

92
```typescript { .api }
93
/**
94
 * Link control - creates and edits hyperlinks with popover interface
95
 * Keyboard shortcut: Ctrl/Cmd + K
96
 * @param props - Link control configuration
97
 */
98
RichTextEditor.Link: React.ComponentType<RichTextEditorLinkControlProps>;
99

100
interface RichTextEditorLinkControlProps extends BoxProps, Omit<RichTextEditorControlBaseProps, 'classNames' | 'styles' | 'vars'>, CompoundStylesApiProps<RichTextEditorLinkControlFactory> {
101
  /** Props passed down to Popover component */
102
  popoverProps?: Partial<PopoverProps>;
103
  /** Determines whether external link control tooltip should be disabled @default false */
104
  disableTooltips?: boolean;
105
  /** Initial state for determining whether the link should be an external @default false */
106
  initialExternal?: boolean;
107
}
108

109
/**
110
 * Unlink control - removes hyperlink from selected text
111
 */
112
RichTextEditor.Unlink: React.ComponentType;
113
```
114

115
**Usage Example:**
116

117
```typescript
118
<RichTextEditor.ControlsGroup>
119
  <RichTextEditor.Link />
120
  <RichTextEditor.Unlink />
121
</RichTextEditor.ControlsGroup>
122
```
123

124
### Special Text Controls
125

126
Controls for superscript, subscript, and other special text formatting.
127

128
```typescript { .api }
129
/**
130
 * Superscript control - formats text as superscript
131
 * Keyboard shortcut: Ctrl/Cmd + .
132
 */
133
RichTextEditor.Superscript: React.ComponentType;
134

135
/**
136
 * Subscript control - formats text as subscript  
137
 * Keyboard shortcut: Ctrl/Cmd + ,
138
 */
139
RichTextEditor.Subscript: React.ComponentType;
140
```
141

142
**Usage Example:**
143

144
```typescript
145
<RichTextEditor.ControlsGroup>
146
  <RichTextEditor.Superscript />
147
  <RichTextEditor.Subscript />
148
</RichTextEditor.ControlsGroup>
149
```
150

151
### Utility Controls
152

153
Controls for document utilities and special content insertion.
154

155
```typescript { .api }
156
/**
157
 * Horizontal rule control - inserts horizontal divider line
158
 */
159
RichTextEditor.Hr: React.ComponentType;
160

161
/**
162
 * Undo control - undoes the last editor action
163
 * Keyboard shortcut: Ctrl/Cmd + Z
164
 */
165
RichTextEditor.Undo: React.ComponentType;
166

167
/**
168
 * Redo control - redoes the last undone action
169
 * Keyboard shortcut: Ctrl/Cmd + Y or Ctrl/Cmd + Shift + Z
170
 */
171
RichTextEditor.Redo: React.ComponentType;
172

173
/**
174
 * Source code control - toggles between WYSIWYG and HTML source view
175
 */
176
RichTextEditor.SourceCode: React.ComponentType;
177
```
178

179
**Usage Example:**
180

181
```typescript
182
<RichTextEditor.ControlsGroup>
183
  <RichTextEditor.Undo />
184
  <RichTextEditor.Redo />
185
  <RichTextEditor.Hr />
186
  <RichTextEditor.SourceCode />
187
</RichTextEditor.ControlsGroup>
188
```
189

190
## Complete Advanced Editor Example
191

192
```typescript
193
import { useEditor } from "@tiptap/react";
194
import StarterKit from "@tiptap/starter-kit";
195
import Underline from "@tiptap/extension-underline";
196
import Superscript from "@tiptap/extension-superscript";
197
import Subscript from "@tiptap/extension-subscript";
198
import Highlight from "@tiptap/extension-highlight";
199
import TextStyle from "@tiptap/extension-text-style";
200
import Color from "@tiptap/extension-color";
201
import { RichTextEditor, Link } from "@mantine/tiptap";
202

203
function AdvancedEditor() {
204
  const editor = useEditor({
205
    extensions: [
206
      StarterKit,
207
      Underline,
208
      Link,
209
      Superscript,
210
      Subscript,
211
      Highlight,
212
      TextStyle,
213
      Color,
214
    ],
215
    content: `
216
      <p>This editor supports <strong>advanced formatting</strong> including:</p>
217
      <ul>
218
        <li><code>Inline code</code> and code blocks</li>
219
        <li><span style="color: #ff6b6b">Colored text</span> and <mark>highlighting</mark></li>
220
        <li><a href="https://example.com">Links</a> with full editing</li>
221
        <li>Mathematical expressions: E=mc<sup>2</sup>, H<sub>2</sub>O</li>
222
      </ul>
223
      <hr>
224
      <blockquote>Advanced controls provide professional editing capabilities</blockquote>
225
    `,
226
  });
227

228
  const colorPickerColors = [
229
    '#25262b', '#868e96', '#fa5252', '#e64980', '#be4bdb', '#7950f2',
230
    '#4c6ef5', '#228be6', '#15aabf', '#12b886', '#40c057', '#82c91e',
231
    '#fab005', '#fd7e14', '#ff6b6b', '#51cf66', '#339af0', '#845ef7',
232
  ];
233

234
  return (
235
    <RichTextEditor 
236
      editor={editor}
237
      onSourceCodeTextSwitch={(isActive) => console.log('Source mode:', isActive)}
238
    >
239
      <RichTextEditor.Toolbar sticky stickyOffset={60}>
240
        {/* History controls */}
241
        <RichTextEditor.ControlsGroup>
242
          <RichTextEditor.Undo />
243
          <RichTextEditor.Redo />
244
        </RichTextEditor.ControlsGroup>
245

246
        {/* Code controls */}
247
        <RichTextEditor.ControlsGroup>
248
          <RichTextEditor.Code />
249
          <RichTextEditor.CodeBlock />
250
        </RichTextEditor.ControlsGroup>
251

252
        {/* Color controls */}
253
        <RichTextEditor.ControlsGroup>
254
          <RichTextEditor.ColorPicker colors={colorPickerColors} />
255
          <RichTextEditor.Color color="#ff6b6b" />
256
          <RichTextEditor.Color color="#51cf66" />
257
          <RichTextEditor.Color color="#339af0" />
258
          <RichTextEditor.UnsetColor />
259
          <RichTextEditor.Highlight />
260
        </RichTextEditor.ControlsGroup>
261

262
        {/* Link controls */}
263
        <RichTextEditor.ControlsGroup>
264
          <RichTextEditor.Link />
265
          <RichTextEditor.Unlink />
266
        </RichTextEditor.ControlsGroup>
267

268
        {/* Special text */}
269
        <RichTextEditor.ControlsGroup>
270
          <RichTextEditor.Superscript />
271
          <RichTextEditor.Subscript />
272
        </RichTextEditor.ControlsGroup>
273

274
        {/* Utilities */}
275
        <RichTextEditor.ControlsGroup>
276
          <RichTextEditor.Hr />
277
          <RichTextEditor.SourceCode />
278
        </RichTextEditor.ControlsGroup>
279
      </RichTextEditor.Toolbar>
280

281
      <RichTextEditor.Content />
282
    </RichTextEditor>
283
  );
284
}
285
```
286

287
## Control Behavior
288

289
### Color Controls
290

291
- **Color Control**: Applies specific color to selected text or at cursor position
292
- **Color Picker**: Opens popover with color palette and custom color picker
293
- **Highlight**: Applies background highlight color (typically yellow)
294
- **Unset Color**: Removes text color, reverting to theme default
295

296
### Link Controls
297

298
- **Link Control**: Opens popover for URL input with external/internal toggle
299
- **Link Editing**: Click existing links to edit URL and external settings
300
- **Keyboard Shortcut**: Cmd/Ctrl+K opens link editor
301
- **Unlink**: Removes hyperlink while preserving text content
302

303
### History Controls
304

305
- **Undo/Redo**: Controls are automatically disabled when no actions available
306
- **State Tracking**: Visual feedback shows when controls are disabled
307
- **Keyboard Shortcuts**: Standard Cmd/Ctrl+Z (undo) and Cmd/Ctrl+Y (redo)
308

309
### Source Code Toggle
310

311
- **View Switching**: Toggles between WYSIWYG and HTML source code view
312
- **Callback Support**: `onSourceCodeTextSwitch` prop receives boolean state
313
- **Content Preservation**: Content is maintained when switching between views
314

315
## Required Extensions
316

317
Advanced controls require specific Tiptap extensions:
318

319
- **Code/CodeBlock**: Included in `@tiptap/starter-kit`
320
- **Colors**: Requires `@tiptap/extension-text-style` and `@tiptap/extension-color`
321
- **Highlight**: Requires `@tiptap/extension-highlight`
322
- **Links**: Use `Link` extension from `@mantine/tiptap` (enhanced version)
323
- **Superscript/Subscript**: Requires `@tiptap/extension-superscript` and `@tiptap/extension-subscript`
324
- **History**: Included in `@tiptap/starter-kit`
325

326
## Customization
327

328
### Color Picker Configuration
329

330
```typescript
331
<RichTextEditor.ColorPicker
332
  colors={['#ff0000', '#00ff00', '#0000ff']}
333
  popoverProps={{ position: 'bottom' }}
334
  colorPickerProps={{ format: 'hex' }}
335
/>
336
```
337

338
### Link Control Configuration
339

340
```typescript
341
<RichTextEditor.Link
342
  initialExternal={false}
343
  disableTooltips={false}
344
  popoverProps={{ 
345
    position: 'bottom',
346
    withinPortal: true 
347
  }}
348
/>
349
```
350

351
### Custom Labels
352

353
```typescript
354
<RichTextEditor
355
  editor={editor}
356
  labels={{
357
    codeControlLabel: "Inline Code",
358
    codeBlockControlLabel: "Code Block",
359
    colorPickerControlLabel: "Text Color",
360
    highlightControlLabel: "Highlight Text",
361
    linkControlLabel: "Add Link",
362
    unlinkControlLabel: "Remove Link",
363
    superscriptControlLabel: "Superscript",
364
    subscriptControlLabel: "Subscript",
365
    undoControlLabel: "Undo",
366
    redoControlLabel: "Redo",
367
    hrControlLabel: "Horizontal Line",
368
    sourceCodeControlLabel: "Source Code",
369
  }}
370
>
371
  {/* advanced controls */}
372
</RichTextEditor>
373
```