Text Editor Configuration

The textEditor option chooses which editor powers text blocks. Two are available:

• TinyMCE (default) - a fully featured rich-text editor with extensive toolbar customization, font controls, and link lists.
• Tiptap (beta) - a lightweight alternative with a streamlined editing experience.

Select one by setting textEditor in your TOPOL_OPTIONS configuration object:

textEditor: "tinymce", // default
// or
textEditor: "tiptap",

Both editors support positioning the toolbar at the bottom of the editor window. See Positioning the toolbar at the bottom for details.

TinyMCE configuration

TinyMCE is the default text editor, running version 6. Customize it by passing a tinyConfig object as part of your TOPOL_OPTIONS configuration object.

INFO

The TinyMCE documentation is available here.

tinyConfig: {
  your_configuration: [
    "value",
  ];
}

WARNING

tinyConfig is merged one level deep. Any key present in it replaces Topol's default for that key outright rather than extending it, so a custom toolbar has to list every button it needs, and a custom toolbar_groups has to redefine any built-in group that should survive.

Configuration examples

Full list of options for customizing the editor's toolbar is available on the TinyMCE documentation page here.

Toolbar customization

The toolbar property lets you control which buttons/tools are available in the text editor's toolbar. To simplify the toolbar or add new options, modify the toolbar value.

Topol default toolbar configuration:

tinyConfig: {
  toolbar: [
    "blocks fontfamily fontsizeinput lineheight bold italic underline strikethrough removeformat nonbreaking | alignleft aligncenter alignright alignjustify link numlist bullist forecolor backcolor mergefields emoticons code more",
  ],
}

Customized toolbar:

tinyConfig: {
  toolbar: [
    "undo redo | bold italic underline strikethrough alignleft aligncenter alignright | bullist numlist outdent indent link image code | forecolor backcolor",
  ],
}

INFO

The default toolbar shows only a subset of what's available, but you can add many more tools. The full set of buttons is listed in the official TinyMCE documentation. To add one, copy its toolbar button identifier into the toolbar array inside tinyConfig.

Two tokens in that string are Topol's own rather than stock TinyMCE: mergefields opens the merge tag menu, and more is a built-in overflow group covering table, special characters, paste-as-text and text direction.

WARNING

The toolbar setting applies to text blocks only. Button blocks and Custom API block text carry their own fixed toolbars, which tinyConfig does not change.

Link list customization

The link_list property lets you define a list of preconfigured links that users can select when adding a hyperlink. This will show a dropdown list in the "Insert/Edit Link" dialog.

tinyConfig: {
  link_list: [
    { title: "View in Browser", value: "https://example.com/view-in-browser" },
    { title: "Unsubscribe", value: "https://example.com/unsubscribe?user={{userId}}" },
    { title: "Privacy Policy", value: "https://example.com/privacy" },
    { title: "Contact Support", value: "https://example.com/contact" },
  ],
}

Font customization

WARNING

When working with fonts, always ensure you set suitable web-safe fonts and operating system fonts as fallback options. Custom fonts are significantly limited across various email clients.

Control which fonts appear in the font family selector with font_family_formats, and the size list with font_size_formats:

tinyConfig: {
  font_size_formats: "8pt 10pt 12pt 14pt 18pt 24pt 36pt",
  font_family_formats:
    "Arial=arial,helvetica,sans-serif; " +
    "Georgia=georgia,palatino; " +
    "Impact=impact,chicago; " +
    "Courier New=courier new,courier,monospace;"
}

INFO

These are the TinyMCE 6 option names. The version 5 spellings fontsize_formats and font_formats are not recognised and are ignored without warning, as tinyConfig values are passed through unchecked.

Hiding tools in a "more" menu

As you add tools to the Toolbar, it can get crowded and harder to use. To keep things tidy, you can move rarely used tools into a custom More menu (⋮).

1) Define the "More" menu

Add a toolbar_groups entry and set toolbar_mode inside your existing tinyConfig option. The example below creates a moretools group and places selected tools inside it.

tinyConfig: {
  toolbar_groups: {
    moretools: {
      icon: "more-drawer",
      tooltip: "More tools", // shown on hover; change to any label you like
      // tools that will live inside the More menu:
      items: "forecolor backcolor mergefields emoticons code",
    },
  },
  toolbar_mode: "floating",
}

2) Update the toolbar layout

Remove tools you just moved (to avoid duplicates) and replace the default more menu with your custom moretools button at the end. If you're not using the more menu, simply add moretools at the end.

tinyConfig: {
  // ... (same as above)
  toolbar: [
    // remove tools already moved to `moretools`
    // and put `moretools` at the end
    "blocks fontfamily fontsizeinput lineheight bold italic underline strikethrough removeformat nonbreaking | alignleft aligncenter alignright alignjustify link numlist bullist moretools",
  ],
}

Rename the button via tooltip, and change its icon via icon. Keep moretools at the end of the toolbar string so it behaves like a drawer for overflow/rare actions. If any item appears both in toolbar and moretools, it will show twice, so remove duplicates from toolbar.

In our example, the resulting tinyConfig option should be as follows:

tinyConfig: {
    toolbar_groups: {
      moretools: {
        icon: "more-drawer",
        tooltip: "More tools",
        items: "forecolor backcolor mergefields emoticons code",
      },
    },
    toolbar_mode: "floating",
    toolbar: [
      "blocks fontfamily fontsizeinput lineheight bold italic underline strikethrough removeformat nonbreaking | alignleft aligncenter alignright alignjustify link numlist bullist moretools",
    ],
  },

Positioning the toolbar at the bottom of the editor window

The toolbar can be locked to the bottom of the editor window, which stops it covering the template above the text block being edited.

To lock the toolbar to the bottom of the editor window, add this option to your TOPOL_OPTIONS configuration object:

// you have to specify the toolbar's alignment
textEditorToolbarBottomPosition: "left" | "center" | "right",

This works with both TinyMCE and Tiptap.

Tiptap editor configuration

INFO

The Tiptap editor is currently in beta. If you encounter any issues or have a feature request, please contact us.

To use the Tiptap editor, set the textEditor option to "tiptap" in your TOPOL_OPTIONS configuration object:

textEditor: "tiptap",

Tiptap configuration options

Tiptap takes a tiptapConfig object, which accepts exactly two keys:

tiptapConfig: {
  //...
},

Toolbar contrast

The light option decides how the toolbar's palette relates to the editor's light or dark mode. With light: true the toolbar contrasts with the surrounding UI, so a dark toolbar sits on a light canvas and a light toolbar on a dark one. Setting it to false flips that pairing.

tiptapConfig: {
  light: true, // default
}

Displaying the merge tag name

A merge tag normally shows its raw value in the editor canvas (for example *|FIRST_NAME|*). Because real values are often long, the showMergeTagText option lets the editor show the tag's human-readable name instead (the text field from its merge tag definition, for example "First name").

tiptapConfig: {
  light: true,
  showMergeTagText: true, // default: false
}

WARNING

This option is available only with the Tiptap text editor. It has no effect under TinyMCE (the default editor), so set textEditor: "tiptap" in your TOPOL_OPTIONS to use it.

This setting changes only what the editor displays, not the exported HTML. The merge tag's value is always serialized, so your ESP receives the same output whether the option is on or off. The display name is resolved by matching each tag's value against your current mergeTags definitions, which means it picks up new names from a dynamic Update Merge Tags call. When a value is not found, the editor falls back to the raw value.