---
title: "Text Editor"
description: "Configure and customize the text editor used in Topol Plugin. Choose between TinyMCE (default) or Tiptap, and tailor each editor to your needs."
url: https://docs.topol.io/email-editor/guide/text-editor-configuration.html
---

# 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:

```ts
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](#positioning-the-toolbar-at-the-bottom-of-the-editor-window) 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](https://www.tiny.cloud/docs/tinymce/6/).

```ts
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. `link_list` is the one exception — see [Link list customization](#link-list-customization).

### Configuration examples

Full list of options for customizing the editor's toolbar is available on the TinyMCE documentation page [here](https://www.tiny.cloud/docs/tinymce/6/toolbar-configuration-options/).

#### 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:**

```ts
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:**

```ts
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](https://www.tiny.cloud/docs/tinymce/6/available-toolbar-buttons/). 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.

```ts
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" },
  ],
}
```

> **INFO**
>
> Unlike every other `tinyConfig` key, `link_list` is extended rather than replaced. If you also configure `mergeTags`, your links are listed first and the merge tags follow, nested under a single group so the two stay apart. Passing `link_list` as a URL string or a function is still supported, but those forms can't be combined — your value is used as-is and merge tags are left out of the dialog.

#### 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`:

```ts
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.

```ts
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.

```ts
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:

```ts
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:

```ts
// 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](https://topol.io/contact/).

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

```ts
textEditor: "tiptap",
```

### Tiptap configuration options

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

```ts
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.

```ts
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](https://docs.topol.io/email-editor/guide/merge-tags.html#defining-merge-tags), for example "First name").

```ts
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](https://docs.topol.io/email-editor/guide/merge-tags.html#update-merge-tags) call. When a value is not found, the editor falls back to the raw value.