Migrating from TinyMCE 4 to TinyMCE 5.

Most configuration changes in TinyMCE 5 only affect complex use cases, such as customized user interface components. The process for setting up a basic TinyMCE 5 instance is the same as TinyMCE 4.

This chapter describes the migration process and workarounds for customers using TinyMCE 4. It describes the settings that require updating prior to migration; and workaround procedures for deprecated, deleted, and updated features.

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

Contents

Editor-Core

To migrate the core TinyMCE editor to TinyMCE 5, review the following sections:

Cloud Delivery

To use TinyMCE 5 from the Tiny Cloud, include this script in your HTML page. Replace 'no-api-key' with your API key.

<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/5/tinymce.min.js" referrerpolicy="origin"></script>

For information on using the latest development and testing builds, see: Cloud deployment guide - Specify editor & plugin versions.

Editor: Changes to API Methods

All TinyMCE 4 API methods for creating UI components have been removed. New methods have been added for TinyMCE 5. For information on creating and customizing UI components, see: User interface components.

Editor: Changes to Settings

TinyMCE 5 includes the following changes to editor-core settings:

New Editor settings

Setting Description

custom_colors

custom_colors is true by default. Setting custom_colors: false removes the custom color picker in the color swatch.

Changed Editor settings

Setting TinyMCE 4 TinyMCE 5

height

Set the height of the editable area of the editor.
Supported number values.

Sets the overall height of the editor, including the menubar, toolbars, and statusbar.
Supports numbers and strings. Assumes strings are a valid CSS value for height.

width

Supported number values.

Supports numbers and strings. Assumes strings are a valid CSS value for width.

resize

true by default.

true by default if the autoresize plugin is not enabled.
false by default if the autoresize plugin is enabled.

Removed Editor settings

  • The file_browser_callback option has been removed for TinyMCE 5. The file_browser_callback option was used to add a file or image browser to TinyMCE. This option was deprecated in version 4.1.0 and replaced by file_picker_callback.

  • insert_button_items - the insert_button_items option was used to specify the toolbar items to display in the insert toolbar button menu. This toolbar button has been removed from TinyMCE 5. For a workaround, configure a custom toolbar button using the following configurations in the tinymce.init:

tinymce.init({
  ...
  toolbar: 'insert',
  setup: function (editor) {
    editor.ui.registry.addMenuButton('insert', {
      icon: 'plus',
      tooltip: 'Insert',
      fetch: function (callback) {
        callback('image link | inserttable');
      }
    });
  }
});
Migrating from file_browser_callback to file_picker_callback

file_picker_callback provides a callback function, removing the requirement for an additional function to manually find and update the element or fire events. file_picker_callback can also update other fields by passing a second argument to update other fields in the dialog. For information on using file_picker_callback, see: Image & file upload options - file_picker_callback.

The following example shows the difference between the removed file_browser_callback setting and file_picker_callback, assuming that browseFiles is a function that opens an external file picker.

TinyMCE 4 - file_browser_callback
tinymce.init({
  ...
  file_browser_callback_types: 'file image media',
  file_browser_callback: function (fieldId, value, type, win) {
    browseFiles(value, type, function (fileUrl) {
      win.document.getElementById(fieldId).value = fileUrl;
    });
  }
});
TinyMCE 5 - file_picker_callback
tinymce.init({
  ...
  file_picker_types: 'file image media',
  file_picker_callback: function (callback, value, meta) {
    browseFiles(value, meta.filetype, function (fileUrl) {
      callback(fileUrl);
    });
  }
});

Browser support: backward compatibility or quirks mode

TinyMCE 5 does not support browsers running in Quirks or backward compatibility modes.

Deprecated Editor settings

New platform detection functions were to the Env API for TinyMCE 5.1, allowing for some older detection properties to be deprecated.

Deprecated Property Alternative Property / Reason for Deprecation Type Original Description

opera

Use browser.isOpera() instead.

Boolean

Constant that is true if the browser is Opera.

webKit

Use browser.isSafari() or browser.isChrome() instead.

Boolean

Constant that is true if the browser is WebKit (Safari/Chrome).

ie

Use browser.version.major and browser.isIE() or browser.isEdge() instead.

Number

Constant that is greater than zero if the browser is IE.

gecko

Use browser.isFirefox() instead.

Boolean

Constant that is true if the browser is Gecko.

mac

Use os.isOSX() or os.isiOS() instead.

Boolean

Constant that is true if the operating system is Mac OS.

iOS

Use os.isiOS() instead.

Boolean

Constant that is true if the operating system is iOS.

android

Use os.isAndroid() instead.

Boolean

Constant that is true if the operating system is android.

desktop

Use deviceType.isDesktop() instead.

Boolean

Constant that is true if the browser is running on a desktop device

contentEditable

All supported browsers now support content editable elements.

Boolean

Constant that is true if the browser supports editing.

caretAfter

All supported browsers now support placing carets after inline blocks.

Boolean

Returns true/false if the browser can or can’t place the caret after a inline block like an image.

range

All supported browsers now support native DOM ranges.

Boolean

Constant that is true if the browser supports native DOM Ranges. IE 9+.

ceFalse

All supported browsers now support contentEditable=false regions.

Boolean

Constant that is true if the browser supports contentEditable=false regions.

Themes

Most themes provided with TinyMCE 4 have been removed from TinyMCE 5 and are now combined in a new responsive theme called Silver. The Silver theme is enabled by default and contains a set of configurable UI components that can be used to replace the functionality of the TinyMCE 4 themes: Modern, Inline, and Inlite.

Removed Theme Replaced by

Modern

Silver

Modern inline

Silver Inline

Inlite(Distraction-free Editor)

Silver (distraction-free configuration)

Mobile

Silver (responsive to small screen touch devices)

Inlite theme removed

The Inlite theme has been removed from TinyMCE 5.

The Inlite theme features are provided by the Quick Toolbar (quickbars) plugin for TinyMCE 5. The Inlite quicklink functionality is now provided by Context Forms.

The following is an example of a TinyMCE 5 quickbars configuration:

{
  theme: 'silver',
  inline: true,
  toolbar: false,
  menubar: false,
  plugins: [ 'quickbars' ]
}

This will provide a similar but improved distraction-free experience in TinyMCE 5.

Modern theme removed

The Modern theme has been removed from TinyMCE 5. The Modern theme’s UI library tinymce.ui.* has also been removed. This change may impact integrations depending upon the level of customization.

Themes: Removed events

Removed event Description

BeforeRenderUi

Fired before the UI was rendered.

Mobile theme

The TinyMCE 4 Mobile theme was deprecated in TinyMCE 5.1. The mobile-optimized editor is loaded on mobile devices. For information on the new mobile experience, see: TinyMCE mobile.

User Interface components

This section covers migrating UI components to TinyMCE 5

Removed UI configuration settings

All inline style configurations have been removed in TinyMCE 5 in favor of modern CSS. This affects all TinyMCE 4 UI component configurations. Skins should be used for custom styling in TinyMCE 5.

Removed style settings:

  • flex

  • border

  • layout - Use the TinyMCE 5 UI component settings to compose a custom layout.

  • spacing

  • padding

  • align

  • pack

  • no-wrap

Changed UI API method namespace

The API methods for registering UI components have moved. They are now part of tinymce.editor.ui.registry.

Changed methods

The following methods have changed for TinyMCE 5:

Old method New method Component

editor.addButton(identifier, configuration)

editor.ui.registry.addButton(identifier, configuration)

Toolbar Buttons

editor.addContextToolbar: (name, spec)

editor.ui.registry.addContextToolbar

Context toolbar

editor.addMenuItem: (name, spec)

editor.ui.registry.addMenuItem

Menu item

editor.addSidebar: (name, spec)

editor.ui.registry.addSidebar: (name, spec)

Sidebar

New methods

The following new methods have been added for creating and using new components:

New method Description

editor.ui.registry.addAutocompleter: (name, spec)

Autocompleter

editor.ui.registry.addContextForm: (name, spec)

Context form

editor.ui.registry.addContextMenu: (name, spec)

Context menu

editor.ui.registry.addMenuButton: (name, spec)

Menu Button

editor.ui.registry.addNestedMenuItem: (name, spec)

Nested menu item

editor.ui.registry.addSplitButton: (name, spec)

Split Button

editor.ui.registry.addToggleButton: (name, spec)

Toggle Button

editor.ui.registry.addToggleMenuItem: (name, spec)

Toggle menu item

editor.ui.registry.addIcon: (name, svgData)

Registers an SVG as an icon

editor.ui.registry.getAll: ()

Returns an array of everything in the UI registry

Custom toolbar buttons

The API methods for adding Custom toolbar buttons have changed for TinyMCE 5. The methods have been moved from editor.* to editor.ui.registry.*. The toolbar button type listbox has been removed and a toggle button type has been added. The button types available in TinyMCE 5 are:

Listbox toolbar buttons are not supported in TinyMCE 5. The recommended replacement toolbar button type is the Split button.

Changed toolbar button API methods

The following methods for creating custom toolbar buttons have been moved for TinyMCE 5. For information on how to use the new methods, see: Toolbar buttons.

Old method New method

editor.addButton()

editor.ui.registry.addButton()

editor.addMenuItem()

editor.ui.registry.addMenuItem()

New toolbar button API methods

New methods have been added for creating common types of toolbar buttons.

New method Description

editor.ui.registry.addToggleButton()

Adds a custom toolbar toggle button.

editor.ui.registry.addSplitButton()

Adds a custom toolbar split button.

editor.ui.registry.addMenuButton()

Adds a custom toolbar menu button.

For information on how to use these methods, see: Types of toolbar buttons.

Changed Toolbar API methods

Old method New method Description

onclick

onAction

onclick is now onAction. onAction now has an API to provide helper functions to the user. For an example migration, see: Migrating onclick to onAction.

cmd

onAction

cmd has been removed as a configuration option. Commands should be executed through onAction now. For an example migration, see: Migrating cmd to onAction.

onpostrender

onSetup

onpostrender has been replaced with onSetup. For an example migration, see: Migrating onpostrender to onSetup.
Migrating onclick to onAction

onclick is now onAction. The callback function given to onAction takes a buttonApi argument which is an object that contains helper functions.

For example:

TinyMCE 4 - onclick
editor.addButton('mybutton', {
  text: 'My Button',
  onclick: function () {
    alert('My Button clicked!');
  }
});
TinyMCE 5 - onAction
editor.ui.registry.addButton('myButton', {
  text: 'My Button',
  onAction: function (buttonApi) {
    alert('My Button clicked!');
  }
});

Each type of toolbar button has a different set of API functions. For information using toolbar buttons, see: Types of toolbar buttons.

Migrating cmd to onAction

cmd: string has been removed. Commands should be executed using onAction instead.

For example:

TinyMCE 4 - cmd
editor.addButton('mybutton', {
  text: 'My Button',
  cmd: 'mceSave'
});
TinyMCE 5 - onAction
editor.ui.registry.addButton('myButton', {
  text: 'My Button',
  onAction: function () {
    editor.execCommand('mceSave');
  }
});
Migrating onpostrender to onSetup

onpostrender has been replaced with onSetup for menu and toolbar components.

There are 3 major changes:

  • onpostrender was only processed when the editor was created, onSetup runs every time a component is rendered. For example: onSetup for a menu item is processed every time the menu rendered.

  • onSetup has an API containing helper functions. Each type of toolbar button has a different API.

  • onSetup can be configured to return a function, which will be automatically be called on the teardown of the component, such as when a menu item’s menu is closed.

    • If a function should only be executed when the editor is first initialized, use the editor.on('init', callback) callback function.

If onSetup listens to any events using editor.on(eventName, callback), it should return a editor.off(eventName, callback) callback to unbind the event on tear down. Unless the event was 'init', onSetup returns function (buttonApi) { ed.off(eventName, callback) }.

For example:

TinyMCE 4 - onpostrender
editor.addButton('currentdate', {
  icon: 'insertdatetime',
  tooltip: 'Insert Current Date',
  onclick: insertDate,
  onpostrender: function monitorNodeChange() {
    var btn = this;
    editor.on('NodeChange', function(e) {
      btn.disabled(e.element.nodeName.toLowerCase() == 'time');
    });
  }
});
TinyMCE 5 - onSetup

In this example, the button’s API contains isDisabled: () => boolean and setDisabled: (state: boolean) => void.

editor.ui.registry.addButton('customDateButton', {
  icon: 'insert-time',
  tooltip: 'Insert Current Date',
  disabled: true,
  onAction: function () {
    editor.insertContent(toTimeHtml(new Date()));
  },
  onSetup: function (buttonApi) {
    const editorEventCallback = function (eventApi) {
      buttonApi.setDisabled(eventApi.element.nodeName.toLowerCase() === 'time');
    };
    editor.on('NodeChange', editorEventCallback);
    return function (buttonApi) {
      editor.off('NodeChange', editorEventCallback);
    }
  }
});
The callback function given to onSetup takes a buttonApi argument which is an object that contains helper functions.

Custom context toolbars

The Context Toolbar accepts toolbar buttons to the editor using the addButton, addToggleButton, addSplitButton, or addMenuButton functions.

The API method for creating custom context toolbars in TinyMCE 5 has changed from editor.addContextToolbar() to editor.ui.registry.addContextToolbar().

For information on Context Toolbars, see: Context toolbar.

Custom menu items

The following configuration options have changed in the custom menu items for TinyMCE 5:

  • addMenuItem has a new configuration.

  • A new method, addNestedMenuItem has been added to the options. The addNestedMenuItem is a method for creating menu items that have a sub-menu with one or more menu items.

  • A new method, addToggleMenuItem has been added to the options. The addToggleMenuItem is a method for creating toggle menu items similar to the toggle toolbar button.

  • The concept of context has been removed from menu item configurations. The menu setting provides this functionality for TinyMCE 5.

To add a custom item to a menu, use the menu setting. All items in a menu need to be declared in order to appear.

For example:

tinymce.init({
  selector: '#editor',
  plugins: 'help',
  menu: {
    help: { title: 'Help', items: 'help | myCustomMenuItem' }
  },
  menubar: 'file edit help',
  setup: function (editor) {
    editor.ui.registry.addMenuItem('myCustomMenuItem', {
      text: 'My Custom Menu Item',
      onAction: function () {
        alert('Menu item clicked');
      }
    });
  }
});

More information * For information on using the menu setting, see: User interface options - menu. * For an example of the default menu items, see: User interface options - Example: The TinyMCE Default Menu Items. * For a list of the available menu controls provided by TinyMCE, see: Menu Items Available for TinyMCE.

New menu item methods

New method Description

editor.ui.registry.addNestedMenuItem()

Adds a menu item that opens a sub-menu.

editor.ui.registry.addToggleMenuItem()

Adds a custom toggle menu item.

Changed menu item methods

Old method New method Description

editor.addMenuItem: (name, spec)

editor.ui.registry.addMenuItem()

Adds a custom basic menu item.

The following examples show custom menu item configurations in TinyMCE 4 and TinyMCE 5:

TinyMCE 4 - example custom menu item

editor.addMenuItem('example', {
  text: 'My menu item',
  context: 'tools',
  onclick: function () {
    editor.insertContent('Hello world!!');
  }
});

TinyMCE 5 - example custom menu item

editor.ui.registry.addMenuItem('example', {
  text: 'My menu item',
  onAction: function () {
    editor.insertContent('Hello world!!');
  }
});

For information on how to use these methods, see: Custom menu items.

Custom dialogs

Dialogs are still opened using the editor.windowManager.open(config) api, however a number of configuration options have changed.

Removed dialog settings

Removed setting Description

height

The dialog component now uses CSS3 and a predefined small, medium, and large template to specify the dimensions.

width

The dialog component now uses CSS3 and a predefined small, medium, and large template to specify the dimensions.

bodyType

bodyType has been merged into the body setting.

onpostrender

onpostrender has been removed for the dialog configuration. The dialog configuration now includes an initialData setting for providing the initial state and an API to fetch or update the data. Refer to this section for more information on how to configure initialData.

url

URL dialogs now have their own API. For more information, see Custom URL dialogs.

New dialog settings

New setting Description

initialData

An object containing the initial value for the dialog components.

onCancel

A callback that is called when the dialog is cancelled without submitting any changes.

onTabChange

A callback that is called when switching tabs in a TabPanel.

Changed dialog settings

Old setting New setting Description

onchange

onChange

onChange now takes a callback function which is passed an API helper function and data.
The onchange callback function provided within individual components has been removed. A single onChange callback function provides the same functionality for all components in TinyMCE 5.
TinyMCE 4 - onchange
const config = {
  title: 'Insert Link',
  body: [
    {
      name: 'text',
      type: 'textbox',
      size: 40,
      label: 'Text to display',
      onchange () {
        data.text = this.value();
      }
    }
  ]
};
TinyMCE 5 - onChange
const config = {
  title: 'Insert Link',
  body: {
    type: 'panel',
    items: [
      {
        name: 'text',
        type: 'input',
        label: 'Text to display'
      }
    ]
  },
  onChange (api, changeData) {
    if (changeData.name === 'text') {
      // Do something with the text to display changes
    }
  }
};

For information about the new dialog configuration, see the Dialog and Dialog components documentation.

Changes to the Custom dialog API

A redesign of the dialog API resulted in the following changes:

Removed Custom dialog APIs
API Type Description

tinymce.WindowManager.getParams()

Method

Returned the params of the last window open call. This was used in iframe based dialog to get params passed from the tinymce plugin.

tinymce.WindowManager.getWindows()

Method

Returned the currently opened window objects.

tinymce.WindowManager.setParams()

Method

Set the params of the last opened window.

tinymce.WindowManager.windows

Property

Returned an array of opened dialogs.
Changed Custom dialog API Methods
Method Description Change

tinymce.WindowManager.alert()

Creates an alert dialog.

A window object is no-longer returned.

tinymce.WindowManager.confirm()

Creates a "confirm" dialog.

A window object is no-longer returned.

tinymce.WindowManager.close()

Closes the top most window.

Only closes dialogs created with open().

For information on the new Dialog API, see: UI components - Dialog instance API.

Custom URL dialogs

The URL dialogs have moved from the editor.windowManager.open() API to the editor.windowManager.openUrl() API. This provides clear separation of the two different types of dialogs in TinyMCE.

Removed URL dialog settings

Old setting New setting Description

file

url

The file setting has been removed in TinyMCE 5 and replaced with url.

New URL dialog settings

New setting Description

onCancel

A callback that is called when the dialog is cancelled without submitting any changes.

onMessage

A callback that is called when the dialog receives a message via the browser window.postMessage API.
TinyMCE 4 - windowManager.open()
editor.windowManager.open({
  title: 'URL Dialog Demo',
  url: 'http://mysite.com/external-page.html'
});
TinyMCE 5 - windowManager.openUrl()
editor.windowManager.openUrl({
  title: 'URL Dialog Demo',
  url: 'http://mysite.com/external-page.html'
});

For information about the new URL dialog configuration, see: URL dialog.

Plugins

The following section covers the changed and removed plugin features for TinyMCE 5.

Removed plugin settings

The height and width settings have been removed from plugin dialogs. The dialog component now uses CSS3 and a predefined small, medium, and large template to specify the dimensions.

The following plugins from TinyMCE 4 do not require height or width options in TinyMCE 5:

Changed plugin settings

TinyMCE 4 TinyMCE 5

autoresize_min_height

min_height

autoresize_max_height

max_height

textcolor_cols

color_cols

textcolor_map

color_map

Changed plugins

These features have either changed or have been deleted in TinyMCE 5.

Plugin name Description

ContextMenu

Context menus are now part of the TinyMCE core. For information on adding custom context menus, see: UI components - Context menu.

TextColor

The text color functionality is now part of the TinyMCE core. For information on using and customizing the text color settings, see: Content appearance options - Text color options.

ColorPicker

The color picker is now part of the TinyMCE core and is enabled by default. For information on disabling the custom color picker, see: Content appearance options - custom_colors.

Custom context menus

The Context menus are part of the core and enabled by default in TinyMCE 5. TinyMCE 5 supports adding registered menu items and allows plugins to register "sections" of the context menu. These sections show or hide depending on the cursor position when the context menu is opened.

For information on using context menus and the default context menu configuration, see: UI components - Context menu.

New context menu methods
New method Description

editor.ui.registry.addContextMenu()

Adds a custom context menu.

For information on Context Menus, see UI components - Context menu.

Spellchecker plugin

The free TinyMCE Spell Checker plugin (spellchecker) was deprecated with the release of TinyMCE 5.4. For details, see the free TinyMCE Spell Checker plugin deprecation notice. The free Spell Checker plugin will be removed in TinyMCE 6.0.

spellchecker_callback has been updated to remove a legacy format for the success callback, which accepted a mapping object of misspelled words to suggestions. For example:

spellchecker_callback: function(method, text, success, failure) {
  var words = text.match(this.getWordCharPattern());
  if (method == "spellcheck") {
    var suggestions = {};
    for (var i = 0; i < words.length; i++) {
      suggestions[words[i]] = ["First", "Second"];
    }
    success(suggestions);
  }
}

The success callback now requires the mapping object to be wrapped in an object with the words key, such as:

spellchecker_callback: function(method, text, success, failure) {
  var words = text.match(this.getWordCharPattern());
  if (method == "spellcheck") {
    var suggestions = {};
    for (var i = 0; i < words.length; i++) {
      suggestions[words[i]] = ["First", "Second"];
    }
    success({ words: suggestions });
  }
}

For information on the spellchecker_callback setting, see: Spell Checker plugin - spellchecker_callback

Table plugin

Changes between TinyMCE 4 and TinyMCE 5:

  • The text field for Styles have been removed from the advanced tab of the dialogs. This simplifies the dialogs for users and gives the editor a stricter control over the table styles, which ensures that the styles are valid.

  • When opening a properties dialog with a single table, row, or cell selected, the dialog will autofill with the relevant existing values. When multiple rows or cells are selected:

    • If the selected rows or cells have the same values, TinyMCE 5 automatically fills the dialog values.

    • If the fields have no existing value or have different values, the dialog fields are left empty.

  • The Border input field in the table properties dialog is now called Border width.