Configuration for registering inline rich text editor marks.
In rich text documents, text nodes are the lowest-level nodes in the tree, containing the text content of the document, along with any formatting.
To implement formatting such as bold, text nodes can contain custom properties refered to as 'marks'.
Custom marks can be added to the editor by registering an RTMarkConfig using RTMarks.register.
The configuration object for registering new rich text mark.
| Property | Type | Description |
|---|---|---|
key* | string | The key of the property added to the text node to enable to mark. |
component* | React.ComponentType | The component used to render the mark. Wraps the editable span element containing the text. |
initializeDataFromFragment | function | Called when creating a new element of this type from a rich text fragment. Should return the initial state of any custom data used in the element. Can be omited if the element simply uses the fragment as its children or not at all. |
shortcuts | | (string | Markdown style shortcuts which activate this mark. |
hotkeys | string[] | A list of keys which, when pressed in unison, insert an element of this type. |
htmlDeserializers | HtmlDeserializerMap | Deserializer functions used to deserialize pasted HTML into this type of mark. |
Text nodes are marked by adding a { [key]: true } property to the node. The default value is true, but string and number values are also supported.
Mark components are just simple React components which wrap the editable span containing the text. The component must render children.
({ children }) => <strong>{children}</strong>
The props passed to inline element components.
| Property | Type | Description |
|---|---|---|
children* | React Children | Renders the editable rich text content. Must be rendered even if the element is void and does not support rich text content (it will render an empty span element required for editor functionality). |
leaf* | RTText | The rich text node being rendered. |
Markdown style shorcuts which enable this mark.
Mark shortcut triggers can be one of two types:
A simple string, which toggles the mark on as soon as it is typed.
A start-end combo, which applies the mark to the text wrapped between the start and end triggers.
The shortcut text is automatically removed when the shortcut is triggered.
| Property | Type | Description |
|---|---|---|
trigger* | | string | The trigger which enables the mark. |
value | boolean | string | number | The value of the mark set onto the text node, defaults to true. |
| Property | Type | Description |
|---|---|---|
start* | string | The shortcut start trigger. |
end* | string | The shortcut end trigger. |
The hotkeys which toggle this mark.
Modifier keys:
Use 'Ctrl' for the Control key (maps to Command key on Mac)
Use 'Alt' from the Alt key (maps to the Option key on Mac).
Use 'Shift'for the Shift key.
For other keys, simply use the character itslef (e.g. 'A', '1', '#'). These are case insensitive.
| Property | Type | Description |
|---|---|---|
keys* | string[] | List of keys used to trigger the action. |
value | boolean | string | number | The value of the mark set onto the text node, defaults to true. |
HTML deserializers are called when HTML data is inserted into the editor, usually as a result of text being copy pasted into the editor from a web page. They should return the mark's value, such as true, or null the mark should not be applied.
HTML deserializers are configured using a { [node name]: HtmlDeserializer } map, where [node name] corresponds to an HTML element node name (in all caps), such a SPAN, A, IMG, etc. Use an asterisk (*) as the node name in order to match against all HTML element types. If multiple registered rich text mark/element types configure a deserializer for the same HTML element, the deserializers will be run one after the other (in the order they were registered) until a non null value is returned. HTML deserializers bubble up, meaning that the most deeply nested elements are deserialized first, followed by their parent element.
The example below demonstrates an HTML deserializer which turns <strong> elements into a 'bold' mark.
deserializers = {
STRONG: (element) => {
return true;
},
};
Callback used to deserialize an HTML mark.
deserializeHtmlMark(
element: HTMLElement,
parent: HTMLElement | null,
children: RTFragment | RTBlockElement[] | null,
): boolean | string | number | null
| Argument | Type | Description |
|---|---|---|
element* | HTMLElement | The HTML element to deserialize. |
parent* | HTMLElement | null | The element's parent element, or null if it has no parent. |
children* | | RTFragment | The element's deserialized child elements or null if the element has no children. |