Migrating from TinyMCE 6 to TinyMCE 7

The process for setting up a basic TinyMCE 7.0 instance is the same as TinyMCE 6.

Most configuration changes in TinyMCE 7.0 only affect complex use cases, such as custom plugins and customized user interface components.

This documentation details the changes in TinyMCE 7.0 that integrators using TinyMCE 6 should consider when upgrading.

For support related to migration, please contact Tiny Support.
Open Source users: please report issues in the TinyMCE GitHub Repository.

Overview

TinyMCE 7 core changes.

For additional details on TinyMCE 7.0 changes, see TinyMCE 7.0 release notes.

Commands and APIs

This section documents the core changes made to TinyMCE 7.0.

Changed

Removed InsertOrderedList and InsertUnorderedList commands from TinyMCE core.

Previously, native list commands were executable through various text patterns, leading to undefined browser behavior due to the embedded list code.

In TinyMCE 7.0, these commands are only available in the Lists plugin.

Example adding list plugin
tinymce.init({
  selector: "textarea",
  plugins: [
    "lists"
  ],
  toolbar: "bullist numlist",
});

remove_trailing_brs property removal from DomParser

The remove_trailing_brs setting was removed from the DomParser API, after being deprecated in TinyMCE 6.5.

Changes to text-pattern defaults to trigger on Space key press.

Applying basic formats such as headings, lists, bold and italic from typing them out in Markdown syntax is considered a must-have for WYSIWYG Editor’s. In previous versions, TinyMCE would only apply these formats once the user presses the Enter key.

TinyMCE 7.0 updates the default behavior of the text-patterns option to apply these formats when the user presses the Space key.

The previous default text_patterns behavior, applying the format on an Enter key press, can be configured by replacing the trigger property with the value 'space'. Learn more about how you can configure text_patterns in the 7.0 Release notes
Updated default text patterns
default: [
  { start: '#', format: 'h1', trigger: 'space' },
  { start: '##', format: 'h2', trigger: 'space' },
  { start: '###', format: 'h3', trigger: 'space' },
  { start: '####', format: 'h4', trigger: 'space' },
  { start: '#####', format: 'h5', trigger: 'space' },
  { start: '######', format: 'h6', trigger: 'space' },
  { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' },
  { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' },
  { start: '-', cmd: 'InsertUnorderedList', trigger: 'space' },
  { start: '>', cmd: 'mceBlockQuote', trigger: 'space' },
  { start: '---', cmd: 'InsertHorizontalRule', trigger: 'space' },
]

For information on the text_patterns, see Text Patterns.

Removed

The autocompleter ch configuration property has been removed. Use the trigger property instead.

Previously, the ch configuration property was used to specify the character that would trigger the autocompleter.

This property was deprecated in TinyMCE 6.2 and has been removed in TinyMCE 7.0. Instead, use the trigger property to specify the string that will trigger the autocompleter.

If editor.ui.registry.addAutocompleter(name, options) was used in your configuration, updating your configuration from ch: '<string>', to trigger: '<string>', is required.

The new trigger option can handle multiple character strings as the trigger.

For more information, visit the updated Autocompleter documentation.

Options

Changed

highlight_on_focus

Previously, the default value for the editor configuration option highlight_on_focus was set to false by default. In TinyMCE 7.0 this option is now by default set to true.

As a result, the focus outline for the editor will by default be displayed when the focus is on the editor.

Customers who have created their own custom skins, or have implemented their own outline and do not intend to use the default will need to add highlight_on_focus: false to their TinyMCE configuration.

This change does not impact editors using inline mode.

Removed

force_hex_color

Previously in TinyMCE 6, all colors in the content HTML were set to use rgb values by default. As the common practice is using hex values, this change has been reverted.

Example
<!-- example before property value conversion -->
// RGB value
<p>Hello <span style="color: rgb(255, 0, 0);">red</span> color</p>
// RGBA value
<p>Hello <span style="color: rgba(255, 0, 0, 0.5);">red</span> color</p>
// HSL value
<p>Hello <span style="color: hsl(0, 100%, 50%);">red</span> color</p>
// RGB value with alpha parameter
<p>Hello <span style="color: rgb(255, 0, 0 / 10%);">red</span> color</p>
// RGB value with calculation
<p>Hello <span style="color: rgb(from hsl(0 100% 50%) 132 132 224);">red</span> color</p>

<!-- example after property value conversion -->
<p>Hello <span style="color: #ff0000">red</span> color</p>
<p>Hello <span style="color: rgba(255, 0, 0, 0.5);">red</span> color</p>
<p>Hello <span style="color: hsl(0, 100%, 50%);">red</span> color</p>
// non-absolute values and absolute values with calculation will not be converted to HEX color
<p>Hello <span style="color: rgb(255, 0, 0 / 10%);">red</span> color</p>
<p>Hello <span style="color: rgb(from hsl(0 100% 50%) 132 132 224);">red</span> color</p>

In TinyMCE 7.0, only RGB values in absolute value like rgb(255, 255, 255) are converted to HEX values. Other RGB formats such as those with non-absolute values, and color options such as RGBA and HSL remain unchanged. The forced_hex_color option has been removed.

Plugins

Changed

Changed the media_url_resolver option to use promises.

In TinyMCE 6 and earlier, the media_url_resolver option provided resolve and reject callbacks, rather than a Promise. In certain circumstances this implementation resulted in unexpected behavior.

In TinyMCE 7, the media_url_resolver option now requires a Promise to be returned.

Old expected value implementing callbacks
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'media',
  toolbar: 'media',
  media_url_resolver: (data, resolve, reject) => {
    if (data.url.indexOf('YOUR_SPECIAL_VIDEO_URL') !== -1) {
      const embedHtml = `<iframe src="${data.url}" width="400" height="400" ></iframe>`;
      resolve({ html: embedHtml });
    } else {
      resolve({ html: '' });
    }
  }
});
New expected value returning a Promise
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'media',
  toolbar: 'media',
  media_url_resolver: (data) => {
    return new Promise((resolve) => {
      if (data.url.indexOf('YOUR_SPECIAL_VIDEO_URL') !== -1) {
        const embedHtml = `<iframe src="${data.url}" width="400" height="400" ></iframe>`;
        resolve({ html: embedHtml });
      } else {
        resolve({ html: '' });
      }
    });
  }
});
Integrators will be required to update there configuration to the reflect the new media_url_resolver changes.

For more information on using media_url_resolver, see media_url_resolver

Removed Plugins

In TinyMCE 7.0 the below plugin has been removed.

Removed open-source Template plugin

The open-source Template plugin and associated config options have been removed in TinyMCE 7.0.

Customers using the template plugin are recommended to upgrade to the premium Templates plugin which provides enhanced template functionality. For more information on the Templates plugin, see: Templates for more details.

Removed Template options:

  • template_cdate_classes

  • template_cdate_format

  • template_mdate_classes

  • template_mdate_format

  • template_replace_values

  • template_preview_replace_values

  • template_selected_content_classes

UI and UX

Changed

Changed how cell and row heights are applied to tables.

Previously, TinyMCE added numerous height styles when resizing table rows such as on the table element, tr elements, and td elements. This resulted in unnecessarily verbose HTML output.

TinyMCE 7.0 addresses this by making a couple of changes:

  • The height input field has been removed from the "Cell Properties" dialog. Now, the "Row Properties" dialog is the only way to update row heights.

  • When a table is resized using the resize handles or the "Row properties" dialog, existing height styles will be stripped from td/th elements where applicable and only applied to the table element and tr elements.

TinyMCE 7.0 does not provide any fallback to revert to the old behavior.

Removed

Force notifications to have a close button

In previous versions of TinyMCE, notifications were able to be displayed without a close button (X). Accessibility is an important component of the editor, and when this button is not in a notification, that notification cannot be closed via keyboard navigation.

As of TinyMCE 7.0, the closeButton property has been removed from the notification API, with all notifications now displaying a visible closeButton. This is to allow notifications to be closed using the Tab key.

Security

Changed

sandbox_iframes

In TinyMCE 6.8.1, the sandbox iframes editor option was introduced to allow iframes to be sandboxed by default when inserted into the editor.

In TinyMCE 7.0, the default for sandbox_iframes will change from false to true, meaning that all iframe elements inserted into the editor will be given the sandbox="" attribute by default, preventing most actions, including scripting and same-origin access, which may break existing editor content or produce undesirable effects.

To prevent any expected iframes from being sandboxed, we recommend adding the source domains of such iframes to the new sandbox_iframes_exclusions option list, and including the domains in the default list where necessary. To prevent all iframes from being sandboxed, set the option sandbox_iframes to false in your editor configuration.

For further details on the sandbox_iframes option, see the the content filtering options, or refer to the security guide, or the TinyMCE 6.8.1 release notes.

convert_unsafe_embeds

In TinyMCE 6.8.1, convert_unsafe_embeds editor option was introduced to allow object and embed elements to be converted by default to the correct element, respective of the MIME type, automatically when inserted into the editor.

In TinyMCE 7.0, the default value for convert_unsafe_embeds will change from false to true, meaning that all object and embed tags will automatically be converted to different elements when inserted to the editor.

TinyMCE has a configuration option that converts object tags to modern equivalents such as <img>, <video> and <audio> tags, such as;

Example of before/after conversion.
<!-- Before Conversion -->
<object type="video/mp4" data="https://sneak-preview.tiny.cloud/3adc27b5-bb2f-49f0-9ccc-72b7c48313b0/bad.mov"></object>

<!-- After Conversion -->
<video src="https://sneak-preview.tiny.cloud/3adc27b5-bb2f-49f0-9ccc-72b7c48313b0/bad.mov" controls="controls"></video>
If this behaviour is undesirable, set convert_unsafe_embeds to false in your editor configuration.

For further details on the convert_unsafe_embeds option, see the content filtering options, or refer to the security guide, or the TinyMCE 6.8.1 release notes.