0
# @mantine/tiptap
1

2
@mantine/tiptap is a comprehensive React rich text editor component library built on top of the Tiptap framework. It provides a familiar editing experience with extensive formatting options, accessibility-focused design, and seamless integration with the Mantine UI library ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @mantine/tiptap
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mantine/tiptap @mantine/core @mantine/hooks @tiptap/react @tiptap/extension-link`
10

11
## Core Imports
12

13
```typescript
14
import { RichTextEditor, useRichTextEditorContext } from "@mantine/tiptap";
15
import type { RichTextEditorProps } from "@mantine/tiptap";
16
```
17

18
For CSS styles:
19

20
```typescript
21
import "@mantine/tiptap/styles.css";
22
// or for CSS layers support:
23
import "@mantine/tiptap/styles.layer.css";
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { useEditor } from "@tiptap/react";
30
import StarterKit from "@tiptap/starter-kit";
31
import { RichTextEditor, Link } from "@mantine/tiptap";
32

33
function App() {
34
  const editor = useEditor({
35
    extensions: [StarterKit, Link],
36
    content: "<p>Hello world!</p>",
37
  });
38

39
  return (
40
    <RichTextEditor editor={editor}>
41
      <RichTextEditor.Toolbar sticky stickyOffset={60}>
42
        <RichTextEditor.ControlsGroup>
43
          <RichTextEditor.Bold />
44
          <RichTextEditor.Italic />
45
          <RichTextEditor.Underline />
46
          <RichTextEditor.Strikethrough />
47
          <RichTextEditor.ClearFormatting />
48
        </RichTextEditor.ControlsGroup>
49

50
        <RichTextEditor.ControlsGroup>
51
          <RichTextEditor.H1 />
52
          <RichTextEditor.H2 />
53
          <RichTextEditor.H3 />
54
          <RichTextEditor.H4 />
55
        </RichTextEditor.ControlsGroup>
56

57
        <RichTextEditor.ControlsGroup>
58
          <RichTextEditor.BulletList />
59
          <RichTextEditor.OrderedList />
60
        </RichTextEditor.ControlsGroup>
61

62
        <RichTextEditor.ControlsGroup>
63
          <RichTextEditor.Link />
64
          <RichTextEditor.Unlink />
65
        </RichTextEditor.ControlsGroup>
66
      </RichTextEditor.Toolbar>
67

68
      <RichTextEditor.Content />
69
    </RichTextEditor>
70
  );
71
}
72
```
73

74
## Architecture
75

76
@mantine/tiptap is designed around several key architectural patterns:
77

78
- **Compound Component Pattern**: The main `RichTextEditor` component provides 30+ static sub-components for building custom toolbars
79
- **Context-based State Management**: Editor state and configuration is shared through React Context
80
- **Tiptap Integration**: Built on top of Tiptap's extensible editor framework with custom extensions
81
- **Mantine Ecosystem Integration**: Full integration with Mantine's styling system, theming, and component patterns
82
- **Accessibility First**: Built-in ARIA labels, keyboard navigation, and screen reader support
83
- **Compound Styling API**: Leverages Mantine's styling system for consistent theming and customization
84

85
## Capabilities
86

87
### Core Components
88

89
Essential components for building rich text editors with layout, content rendering, and basic controls.
90

91
```typescript { .api }
92
function RichTextEditor(props: RichTextEditorProps): JSX.Element;
93

94
interface RichTextEditorProps extends BoxProps, StylesApiProps<RichTextEditorFactory>, ElementProps<'div'> {
95
  /** Tiptap editor instance */
96
  editor: Editor | null;
97
  /** Determines whether code highlight styles should be added @default true */
98
  withCodeHighlightStyles?: boolean;
99
  /** Determines whether typography styles should be added @default true */
100
  withTypographyStyles?: boolean;
101
  /** Called if RichTextEditor.SourceCode clicked */
102
  onSourceCodeTextSwitch?: (isSourceCodeModeActive: boolean) => void;
103
  /** Labels that are used in controls */
104
  labels?: Partial<RichTextEditorLabels>;
105
  /** Child editor components */
106
  children: React.ReactNode;
107
}
108
```
109

110
[Core Components](./core-components.md)
111

112
### Text Formatting Controls
113

114
Pre-built controls for text styling including bold, italic, underline, strikethrough, and formatting removal.
115

116
```typescript { .api }
117
// Text formatting controls
118
RichTextEditor.Bold: React.ComponentType;
119
RichTextEditor.Italic: React.ComponentType;
120
RichTextEditor.Underline: React.ComponentType;
121
RichTextEditor.Strikethrough: React.ComponentType;
122
RichTextEditor.ClearFormatting: React.ComponentType;
123
```
124

125
[Text Formatting Controls](./text-formatting.md)
126

127
### Structure Controls
128

129
Controls for document structure including headings, lists, blockquotes, and alignment options.
130

131
```typescript { .api }
132
// Heading controls
133
RichTextEditor.H1: React.ComponentType;
134
RichTextEditor.H2: React.ComponentType;
135
RichTextEditor.H3: React.ComponentType;
136
RichTextEditor.H4: React.ComponentType;
137
RichTextEditor.H5: React.ComponentType;
138
RichTextEditor.H6: React.ComponentType;
139

140
// List controls
141
RichTextEditor.BulletList: React.ComponentType;
142
RichTextEditor.OrderedList: React.ComponentType;
143
RichTextEditor.TaskList: React.ComponentType;
144

145
// Alignment controls
146
RichTextEditor.AlignLeft: React.ComponentType;
147
RichTextEditor.AlignCenter: React.ComponentType;
148
RichTextEditor.AlignRight: React.ComponentType;
149
RichTextEditor.AlignJustify: React.ComponentType;
150
```
151

152
[Structure Controls](./structure-controls.md)
153

154
### Advanced Controls
155

156
Advanced formatting options including code blocks, color controls, links, and specialized text features.
157

158
```typescript { .api }
159
// Code controls
160
RichTextEditor.Code: React.ComponentType;
161
RichTextEditor.CodeBlock: React.ComponentType;
162

163
// Color controls
164
RichTextEditor.Color: React.ComponentType<RichTextEditorColorControlProps>;
165
RichTextEditor.ColorPicker: React.ComponentType<RichTextEditorColorPickerControlProps>;
166
RichTextEditor.Highlight: React.ComponentType;
167
RichTextEditor.UnsetColor: React.ComponentType;
168

169
// Link controls
170
RichTextEditor.Link: React.ComponentType<RichTextEditorLinkControlProps>;
171
RichTextEditor.Unlink: React.ComponentType;
172

173
// Special formatting
174
RichTextEditor.Superscript: React.ComponentType;
175
RichTextEditor.Subscript: React.ComponentType;
176
RichTextEditor.Blockquote: React.ComponentType;
177
RichTextEditor.Hr: React.ComponentType;
178
```
179

180
[Advanced Controls](./advanced-controls.md)
181

182
### Context and Hooks
183

184
React Context and hooks for accessing editor state, configuration, and building custom controls.
185

186
```typescript { .api }
187
function useRichTextEditorContext(): RichTextEditorContext;
188

189
interface RichTextEditorContext {
190
  editor: Editor | null;
191
  getStyles: GetStylesApi<RichTextEditorFactory>;
192
  labels: RichTextEditorLabels;
193
  withCodeHighlightStyles: boolean | undefined;
194
  withTypographyStyles: boolean | undefined;
195
  variant: string | undefined;
196
  unstyled: boolean | undefined;
197
  onSourceCodeTextSwitch?: (isSourceCodeModeActive: boolean) => void;
198
}
199
```
200

201
[Context and Hooks](./context-hooks.md)
202

203
### Extensions
204

205
Tiptap extensions with enhanced functionality for links and task lists, including keyboard shortcuts and custom styling.
206

207
```typescript { .api }
208
const Link: Extension;
209
function getTaskListExtension<T>(TipTapTaskList: T): T;
210
```
211

212
[Extensions](./extensions.md)
213

214
### Labels and Internationalization
215

216
Comprehensive labeling system for accessibility and internationalization support with 40+ customizable labels.
217

218
```typescript { .api }
219
const DEFAULT_LABELS: RichTextEditorLabels;
220

221
interface RichTextEditorLabels {
222
  boldControlLabel: string;
223
  italicControlLabel: string;
224
  underlineControlLabel: string;
225
  strikeControlLabel: string;
226
  clearFormattingControlLabel: string;
227
  linkControlLabel: string;
228
  unlinkControlLabel: string;
229
  bulletListControlLabel: string;
230
  orderedListControlLabel: string;
231
  h1ControlLabel: string;
232
  h2ControlLabel: string;
233
  h3ControlLabel: string;
234
  h4ControlLabel: string;
235
  h5ControlLabel: string;
236
  h6ControlLabel: string;
237
  blockquoteControlLabel: string;
238
  alignLeftControlLabel: string;
239
  alignCenterControlLabel: string;
240
  alignRightControlLabel: string;
241
  alignJustifyControlLabel: string;
242
  codeControlLabel: string;
243
  codeBlockControlLabel: string;
244
  subscriptControlLabel: string;
245
  superscriptControlLabel: string;
246
  colorPickerControlLabel: string;
247
  unsetColorControlLabel: string;
248
  highlightControlLabel: string;
249
  undoControlLabel: string;
250
  redoControlLabel: string;
251
  hrControlLabel: string;
252
  sourceCodeControlLabel: string;
253
  tasksControlLabel: string;
254
  tasksSinkLabel: string;
255
  tasksLiftLabel: string;
256
  colorControlLabel: (color: string) => string;
257
  colorPickerColorLabel: (color: string) => string;
258
  linkEditorInputLabel: string;
259
  linkEditorInputPlaceholder: string;
260
  linkEditorExternalLink: string;
261
  linkEditorInternalLink: string;
262
  linkEditorSave: string;
263
  colorPickerCancel: string;
264
  colorPickerClear: string;
265
  colorPickerColorPicker: string;
266
  colorPickerPalette: string;
267
  colorPickerSave: string;
268
}
269
```
270

271
[Labels and Internationalization](./labels-i18n.md)