Rich text editor

Rich text editors allow the user to format text. In ActiveCampaign, these are often used when formatting emails, or in builders (such as the Pages builder, Campaigns builder, etc.)

Overview

Resources

Install


yarn add @activecampaign/camp-components-rich-text-editor

Usage

The Camp rich text editor is built with flexibility in mind in order to meet a variety of needs within the platform. For a React-based end-to-end editing experience, we take advantage of a library called Lexical that offers a powerful and highly customizable rich text editor experience. You can customize exactly what functionality you need using that editor, and we also export the editor-agnostic building blocks in case you need to use something other than Lexical. Below we will walk through different ways the editor can be used starting with the most common.

The Kitchen Sink

The easiest way to insert the React-based (Lexical) WYSIWYG editor on the page with all the Camp rich text editing functionality included, is to use the ”Kitchen Sink.” This is what is shown in the demo above. Here is how that is being implemented:


import React, { useRef } from 'react';
import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
import { LexicalEditor } from 'lexical';
import { $generateHtmlFromNodes } from '@lexical/html';
 
export const kitchenSink: StoryFn = () => {
  // How to get the editor instance.
 const editorRef = useRef<LexicalEditor>(null);
 
  // HTML content to be imported.
 const htmlContent = '<h1>This is a Lexical Rich Text Editor</h1><p>Content goes here</p>';
 
 return (
   <RichTextEditor.LexicalKitchenSink
     editorRef={editorRef}
     onChange={(editorState, editor) => {
       editorState.read(() => {
         const htmlString = $generateHtmlFromNodes(editor, null);
         // will output the HTML content of your editor as you type.
         console.log(htmlString);
       });
     }}
   >
     <RichTextEditor.SerializeHtmlContentPlugin htmlContent={htmlContent} />
   </RichTextEditor.LexicalKitchenSink>
 );
};

Customized editors

You can also customize the editor by only pulling in the pieces you need. We export each button and piece of functionality individually as well as the groups. Here is a list of the current plugins as of Q3 2024:

Block type (paragraph, heading, etc.)
Font family
Font size
Text decoration (bold, italics, underline, strikethrough)
Text color and background color
Align text
Lists
Link
Indent and outdent
OnBlur
Uppercase
Superscript and subscript
Emoji picker
Special characters
Ability to clear all text formatting
Add image
Add personalization

Here is an example of an editor with only specific buttons:


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function customButtons() {
  return (
    <RichTextEditor.LexicalComposer>
      <RichTextEditor.Toolbar>
        <RichTextEditor.RichTextEditorRow>
          <RichTextEditor.LexicalBlockTypes />
          <RichTextEditor.LexicalBold />
          <RichTextEditor.LexicalEmojiPicker />
        </RichTextEditor.RichTextEditorRow>
      </RichTextEditor.Toolbar>
      <RichTextEditor.Textarea id="rte">
        <RichTextEditor.LexicalRichTextPlugin />
      </RichTextEditor.Textarea>
    </RichTextEditor.LexicalComposer>
  );
}

We also export common groups. Here is a list of those:

**Typography: **includes block types, font family, font size
**Text styles: **includes bold, italics, underline
**Text colors: **includes color, background color
**Text format: **includes align text, lists
**Indent: **includes Indent, Outdent
**Special format: - **includes strikethrough, uppercase, superscript, subscript, emojis, special characters, clear formatting

Here is an example of an editor showing specific groups in multiple rows:


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function customGroups() {
  return (
    <RichTextEditor.LexicalComposer>
      <RichTextEditor.Toolbar>
        <RichTextEditor.RichTextEditorRow>
          <RichTextEditor.LexicalTypographyGroup />
          <RichTextEditor.EditorExpand ariaLabel="expand the editor" />
        </RichTextEditor.RichTextEditorRow>
        <RichTextEditor.RichTextEditorRow>
          <RichTextEditor.LexicalTextColorGroup />
          <RichTextEditor.LexicalClearFormatting />
        </RichTextEditor.RichTextEditorRow>
      </RichTextEditor.Toolbar>
      <RichTextEditor.Textarea id="rte">
        <RichTextEditor.LexicalRichTextPlugin />
      </RichTextEditor.Textarea>
    </RichTextEditor.LexicalComposer>
  );
}

Other components are also exported for maximum layout flexibility:

Row (<RichTextEditor.Row />)
Divider (<RichTextEditor.Divider />)
Expand (<RichTextEditor.EditorExpand />)

Input example

The rich text editor usage is not bound solely to textareas. The rich text editor can be used with an input as well. Here is an example:


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function RTEAsInput() {
  const mockCustomObjectFields = [
    {
      id: '1',
      name: 'contacts',
      key: 'contactPersTags',
      label: 'OBJECTS',
      fields: [
        {
          id: '2',
          persTag: 'CO:SomethingCool:2',
          value: 'Something',
        },
      ],
      defaultCollapsed: true,
    },
  ];
  return (
    <RichTextEditor.LexicalPersonalizationInput
      data={mockCustomObjectFields}
      userContent=""
      showEmojiPicker
      showPersonalizationButton
    />
  );
}

Fully custom Lexical editor

As the platform continues to mature, new use cases will require the creation of additional pre-built editor patterns. You can work with the Camp team to create an extremely custom rich text editing experience. Below is an example of a pattern built for the Automations team called PersonalizationEmojiPlainText that is now available for anyone to use. It includes a Rich Text Editor that imports and exports plain text and allows for emojis and Personalization tags. If you have a custom need, reach out to us in #help-design-systems and we can work with you to make it happen.

The current props available and their descriptions for this custom component can be found here (select the tab titled RichTextEditor.PersonalizationEmojiPlainText, beneath the example RichTextEditor).


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
import { mockCustomObjectFields } from '...';
 
function personalizationEmojiPlainText() {
  return (
    <RichTextEditor.PersonalizationEmojiPlainText
      userContent=""
      showPersonalizationButton
      showEmojiPicker
      data={mockCustomObjectFields}
      onSave={(msg) => console.log('msg', msg)}
      placeholder="Type '%' to add a personalization tag."
    />
  );
}

Non-Lexical

You can also use the basic styled Camp elements to wire up to your own editor if you cannot use Lexical. Those are exported individually and follow the same naming conventions (minus “Lexical”). For example, the Bold button is simply <Bold />.


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function nonLexicalPlugins() {
  return (
    <RichTextEditor.Toolbar>
      <RichTextEditor.RichTextEditorRow>
        <RichTextEditor.Bold />
        <RichTextEditor.Italics />
        <RichTextEditor.Underline />
        <RichTextEditor.Strikethrough />
        <RichTextEditor.ClearFormatting />
      </RichTextEditor.RichTextEditorRow>
    </RichTextEditor.Toolbar>
  );
}

Custom plugins and nodes

One of the great benefits of Lexical is how flexible it is in terms of creating your own plugins. We have already created many of them for you, but below is some guidance if you need to create one yourself.

Editor context

First of all, it is important to note that since the Camp rich text editor Lexical instance is precompiled, you cannot use Lexical’s recommended approach of getting the editor instance using the useLexicalComposerContext() hook. But there is another way to access the editor instance, which is to use a ref. See below for an example of how to set it and pass it in to the “Kitchen Sink.”


import React, { useRef } from 'react';
import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
import { LexicalEditor } from 'lexical';
 
export const editorRef: StoryFn = () => {
  // Set the editor instance to ref.
 const editorRef = useRef<LexicalEditor>(null);
 
  // Pass it into component.
 return <RichTextEditor.LexicalKitchenSink editorRef={editorRef} />;
};

Adding a custom plugin

You can add your own custom Lexical plugins to the Camp rich text editor. Below is a simplified example using the <LexicalKitchenSink /> adapted from an implementation by the Message Variables team.


import { useEffect } from 'react';
import { LexicalKitchenSink } from '@activecampaign/camp-components-rich-text-editor';
import { $generateNodesFromDOM } from '@lexical/html';
import { $getRoot, $insertNodes, $setSelection } from 'lexical';
 
// Example Plugin Code
export const InsertContentPlugin = ({ htmlString, editor }): null => {
  const currentEditor = editor.current;
  useEffect(() => {
    return currentEditor.update(() => {
      const parser = new DOMParser();
      const dom = parser.parseFromString(htmlString, 'text/html');
      const nodes = $generateNodesFromDOM(currentEditor, dom);
 
      $getRoot().selectStart();
      $insertNodes(nodes);
      // remove focus from div after nodes are inserted
      $setSelection(null);
    });
  }, [currentEditor, htmlString]);
  return null;
};
 
// Example Rich Text Editor Component Code
const editorRef = createRef<LexicalEditor>();
// value of rich text editor
const [lexicalValue, setLexicalValue] = useState(initialValue);
 
function handleChange(value): void {
 const parser = new DOMParser();
 const dom = parser.parseFromString(value, 'text/html');
 setLexicalValue(value);
}
 
<LexicalKitchenSink editorRef={editorRef} onChange={handleChange}>
  <InsertContentPlugin htmlString={lexicalValue} editor={editorRef} />
</LexicalKitchenSink>

Plugins can be used for all kinds of functionality, but a common one is when needing to import data from the database into the rich text editor and/or to save the editor content into a database. Importing data into the editor is called serialization and exporting is called deserialization and we have docs specifically for that here.

Once again, if you have custom plugin needs, feel free to reach out in #help-design-systems if you need the Design Systems team to help build those. Also, if they are reusable across the platform, let us know and we will help you get them into Camp so that everyone can benefit!

Adding a custom node

Lexical Nodes are basic building blocks that represent the underlying data model of the rich text editor. Some core nodes are Element (think HTML elements), Text (the foundation of all textual content), and Decorator Nodes (think custom Nodes like YouTube videos, Tweets, etc.). One of the most powerful features of Lexical is that it allows you to extend or add new Nodes.

For example, we have done that for Personalization. In the new editor, Personalization tags show up as Camp chips with the name of the tag and the lightning bolt icon. They can be clickable. For that Lexical Node, we extended Lexical’s Decorator Node, since the visual display is basically a React element. See below for the full code as of Q3 2024:


import {
 $applyNodeReplacement,
 DOMConversion,
 DOMConversionMap,
 DOMConversionOutput,
 DOMExportOutput,
 DecoratorNode,
 NodeKey,
 SerializedLexicalNode,
 Spread,
} from 'lexical';
import React from 'react';
import {
 PersonalizationChip,
 PersonalizationChipProps,
} from '../../plugins/Personalization/PersonalizationChip';
 
function convertPersonalizationElement(domNode: HTMLElement): DOMConversionOutput | null {
 const personalizationChipContent = domNode.textContent?.substring(
   1,
   domNode.textContent.length - 1
 );
 
 const personalizationValue = domNode.dataset.persTag;
 
 if (personalizationChipContent && personalizationValue) {
   const node = $createPersonalizationNode({
     personalizationChipContent,
     personalizationValue,
   });
   return {
     node,
   };
 }
 return null;
}
 
export class PersonalizationNode extends DecoratorNode<JSX.Element> {
 __personalizationChipContent: string;
 __personalizationValue: string;
 
 static getType(): string {
   return 'personalization';
 }
 
 static clone(node: PersonalizationNode): PersonalizationNode {
   return new PersonalizationNode(
     node.__personalizationChipContent,
     node.__personalizationValue,
     node.__key
   );
 }
 
 static importJSON(serializedNode: SerializedPersonalizationNode): PersonalizationNode {
   const personalizationDode = $createPersonalizationNode(serializedNode);
   return personalizationDode;
 }
 
 exportJSON(): SerializedPersonalizationNode {
   return {
     personalizationChipContent: this.__personalizationChipContent,
     personalizationValue: this.__personalizationValue,
     type: 'personalization',
     version: 1,
   };
 }
 
 static importDOM(): DOMConversionMap | null {
   return {
     span: (domNode: HTMLElement): DOMConversion<HTMLElement> | null => {
       if (!domNode.hasAttribute('data-lexical-personalization')) {
         return null;
       }
       return {
         conversion: convertPersonalizationElement,
         priority: 1,
       };
     },
   };
 }
 
 constructor(personalizationChipContent: string, personalizationValue: string, key?: NodeKey) {
   super(key);
   this.__personalizationChipContent = personalizationChipContent;
   this.__personalizationValue = personalizationValue;
 }
 
 createDOM(): HTMLElement {
   const dom = document.createElement('span');
   return dom;
 }
 
 exportDOM(): DOMExportOutput {
   const element = document.createElement('span');
   element.dataset.lexicalPersonalization = this.__personalizationValue;
   element.textContent = `%${this.__personalizationValue}%`;
   return { element };
 }
 
 decorate(): JSX.Element {
   return (
     <PersonalizationChip
       personalizationChipContent={this.__personalizationChipContent}
       personalizationValue={this.__personalizationValue}
     />
   );
 }
 
 updateDOM(): false {
   return false;
 }
}
 
export function $createPersonalizationNode({
 personalizationChipContent,
 personalizationValue,
}: PersonalizationChipProps): PersonalizationNode {
 const personalizationNode = new PersonalizationNode(
   personalizationChipContent,
   personalizationValue
 );
 return $applyNodeReplacement(personalizationNode);
}
 
export type SerializedPersonalizationNode = Spread<PersonalizationChipProps, SerializedLexicalNode>;

Nodes follow Javascript class-based conventions. We have written a few for Camp, which you can reference if you need to create your own and Lexical’s documentation is also very helpful here.

Serialization and deserialization

Data can be imported (serialized) and exported (deserialized) into a Lexical editor using either HTML or JSON. Our platform tends to prefer storing HTML so all our examples below show that. You can write your own serialization plugin (see plugins tab), and below are a few ready-made plugins as well as a custom example:

Serialize HTML content

You can easily import (serialize) HTML content into one of our editors using this prebuilt plugin like so:


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function serializationHtml() {
  const htmlContent = `<h1>This is HTML content</h1>
   <p>It is imported using Camp's prebuilt <code>SerializeHtmlContentPlugin</code>.</p>`;
 
  return (
    <RichTextEditor.LexicalKitchenSink>
      <RichTextEditor.SerializeHtmlContentPlugin htmlContent={htmlContent} />
    </RichTextEditor.LexicalKitchenSink>
  );
}

Deserialize HTML content

You can also easily export (deserialize) HTML content from one of our editors using our prebuilt onSave or onSavePlainText plugins:


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function onSave() {
  return (
    <RichTextEditor.LexicalKitchenSink placeholder="See the console for your HTML output">
      <RichTextEditor.OnSave onSave={(msg) => console.log('msg', msg)} />
    </RichTextEditor.LexicalKitchenSink>
  );
}


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
 
function onSavePlainText() {
  return (
    <RichTextEditor.LexicalKitchenSink placeholder="See the console for your HTML output">
      <RichTextEditor.OnSavePlainText onSave={(msg) => console.log('msg', msg)} />
    </RichTextEditor.LexicalKitchenSink>
  );
}

Serialize plain text content

We wrote a custom plugin for the Automations team to be able to import plain text while creating Personalization tags. This is now available in Camp to be used by anyone.


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
import { mockCustomObjectFields } from '...';
 
export const serializePlainTextPersonalization: StoryFn = () => {
  return (
    <RichTextEditor.LexicalKitchenSink customNodes={[RichTextEditor.PersonalizationNode]}>
      <RichTextEditor.LexicalPersonalization data={mockCustomObjectFields} />
      <RichTextEditor.SerializePlainTextContentPlugin
        content="Hello, this is a personalization tag: %LASTNAME%"
        data={mockCustomObjectFields}
      />
    </RichTextEditor.LexicalKitchenSink>
  );
};

Custom serialization plugins

You can also write your own custom serialization plugin. As mentioned in our custom plugins documentation, you cannot get the editor instance from the Lexical-recommended useLexicalComposerContext() hook. You have to instead use a ref to get it. The below example shows how to serialize HTML content while creating Personalization tags (note: this example implies a specific Personalization tags data structure).


import * as RichTextEditor from '@activecampaign/camp-components-rich-text-editor';
import { mockCustomObjectFields } from '...';
 
// Find readable match in subarrays of subarrays.
function findReadableMatch(array, persTag) {
 for (const subArray of array) {
   for (const item of subArray) {
     if (item.persTag === persTag) {
       return item;
     }
   }
 }
 return undefined;
}
 
// Custom Plugin to serialize HTML content while creating Personalization tags.
function SerializeHtmlContentWithPersonalizationPlugin({ htmlContent, editor, data }): null {
 const currentEditor = editor.current;
 if (currentEditor.getEditorState().isEmpty()) {
   currentEditor.update(() => {
     const personalizationDataFields = data?.map(({ fields }) => fields);
 
     const userDataReplacingPersonalizationValues = htmlContent.replace(
       /(%[\s\S]*?%)/g,
       (match) => {
         const contentWithoutPercentSign = match.substring(1, match.length - 1);
         const readableMatch = findReadableMatch(
           personalizationDataFields,
           contentWithoutPercentSign
         );
 
         return readableMatch
           // Our Camp Personalization plugin knows to create the tag based on the data attribute.
           ? `<span data-lexical-personalization data-pers-tag=${readableMatch.persTag}>%${readableMatch.value}%</span>`
           : match;
       }
     );
 
     const parser = new DOMParser();
     const dom = parser.parseFromString(userDataReplacingPersonalizationValues, 'text/html');
 
     const nodes = $generateNodesFromDOM(currentEditor, dom);
 
     $getRoot().select();
     $getRoot().clear();
 
     $insertNodes(nodes);
   });
 }
 return null;
}
 
function customSerializationExample() {
 const editorRef = useRef<LexicalEditor>(null);
 
 const htmlContent = '<h1>This is HTML Content</h1><p>With personalization tags: %LASTNAME%</p>';
 
 return (
   <RichTextEditor.LexicalKitchenSink
     editorRef={editorRef}
     customNodes={[RichTextEditor.PersonalizationNode]}
   >
     <RichTextEditor.LexicalPersonalization data={mockCustomObjectFields} />
     <SerializeHtmlContentWithPersonalizationPlugin
       htmlContent={htmlContent}
       data={mockCustomObjectFields}
       editor={editorRef}
     />
   </RichTextEditor.LexicalKitchenSink>
 );
};

Fully control serialized data

Lexical’s functions to import HTML strip out a lot of elements and attributes by default, leaving the HTML clean and secure. However, you may want to keep many of the elements and attributes that Lexical decides to strip out. This is where Lexical’s flexibility shines. It gives you the ability to extend and even create new Lexical Nodes - the basic building blocks of rich text editing (e.g., text, elements, etc.). Our Camp rich text editor Kitchen Sink ships with a node extension built in called StyledTextNode that keeps all CSS attributes on imported elements. Also, below is an example of a plugin that ensures Lexical doesn’t strip certain elements by default (div, blockquote, and table elements) while also preserving some of the style attributes needed for those elements.


import {
 DOMConversionMap,
 DOMConversionOutput,
 ElementNode,
 $applyNodeReplacement,
 NodeKey,
} from 'lexical';
 
// Keep elements and attributes that Lexical strips out by default.
export class ExtendedElementNode extends ElementNode {
 // Attributes we want to keep.
 __tag: string;
 __classname: string;
 __style: string;
 __vAlign: string;
 
 static getType(): string {
   return 'extended-element';
 }
 
 static clone(node: ExtendedElementNode): ExtendedElementNode {
   return new ExtendedElementNode(
     node.__key,
     node.__tag,
     node.__classname,
     node.__style,
     node.__vAlign
   );
 }
 
 // Intercept Lexical's importing and add a conversion function.
 static importDOM(): DOMConversionMap | null {
   return {
     div: () => ({
       conversion: convertElement,
       priority: 1,
     }),
     blockquote: () => ({
       conversion: convertElement,
       priority: 1,
     }),
     table: () => ({
       conversion: convertElement,
       priority: 1,
     }),
     tbody: () => ({
       conversion: convertElement,
       priority: 1,
     }),
     tr: () => ({
       conversion: convertElement,
       priority: 1,
     }),
     td: () => ({
       conversion: convertElement,
       priority: 1,
     }),
   };
 }
 
 constructor(tag, classname, style, vAlign, key?: NodeKey) {
   super(key);
   this.__tag = tag;
   this.__classname = classname;
   this.__style = style;
   this.__vAlign = vAlign;
 }
 
 // Create the actual element to be used and add attributes.
 createDOM(): HTMLElement {
   const tag = this.__tag;
   const classname = this.__classname;
   const style = this.__style;
   const vAlign = this.__vAlign;
   const dom = document.createElement(tag);
   vAlign && dom.setAttribute('valign', vAlign);
   classname && dom.setAttribute('class', classname);
   style && dom.setAttribute('style', style);
   return dom;
 }
 
 updateDOM(): false {
   return false;
 }
}
 
// Conversion function to be passed into import.
function convertElement(domNode: Node): DOMConversionOutput {
 const domNode_ = domNode as HTMLElement;
 const tag = domNode_.nodeName.toLowerCase();
 const classname = domNode_.getAttribute('class') || '';
 const style = domNode_.getAttribute('style') || '';
 const vAlign = domNode_.getAttribute('valign') || '';
 
 const node = $createExtendedElement(tag, classname, style, vAlign);
 
 return { node };
}
 
// Use Lexical's node replacement function to replace the node with our extended node.
export function $createExtendedElement(tag, classname, style, vAlign): ExtendedElementNode {
 const extendedElementNode = new ExtendedElementNode(tag, classname, style, vAlign);
 return $applyNodeReplacement(extendedElementNode);
}

Accessibility

tab to navigate between rich text editor items
space or enter to open a dropdown menu
up and down arrows to navigate between menu items within a dropdown
space or enter to make a selection

Similar components

Color Picker

Allows users to select a color from a range of colors.

Textarea

A multi-line text input field that allows users to enter longer form content.