Blueprint by Tiny
Return to Tiny.cloud
Return to Tiny.cloudTry TinyMCE for Free
Search by
Text "TinyMCE" with an arrow pointing from a 4 to 5.

How to migrate from TinyMCE 4 to TinyMCE 5

Ben Long

August 17th, 2020

Written by

Ben Long
Ben Long

Category

How-tos & Tutorials

TinyMCE 5 is the next generation WYSIWYG editor bridging the gap between a great UX, developer-friendly features, and cutting edge functionality. TinyMCE has always been the staple in bringing the best content creation experience to a wide range of established and emerging enabling technologies - see 9 products you can build with TinyMCE.

If you haven’t yet migrated from TinyMCE 4 to TinyMCE 5, now is the time to do it!

TinyMCE 5 brings significant improvements to the editor, including:

  • The most advanced, intuitive, mobile rich text editing experience on the market - read more about Tiny mobile
  • A modern and more flexible UI, enabling you to create the best possible UX for the products you’re building
  • The ability to configure skins to match the design system used in your product, app or website, plus a skinning tool to assist with skin creation
  • 6 new premium plugins, including Advanced Tables, Case Change, Checklist, Page Embed, Permanent Pen, plus Skins and Icon Packs
  • Next level support for creating and editing tables, so users can present data in the most efficient and effective way

Check out a demo for yourself on our home page.

We previously announced the end of support for TinyMCE 4.x - officially supported through to December 31, 2020, which will enable us to focus more of our efforts on the roadmap for TinyMCE 5 and beyond.

Further to this, access to online services for TinyMCE 4 will be switched off on the following dates:

  • CacheFly CDN (http://tinymce.cachefly.net/) - November 30 2020
  • TinyMCE CDN (https://cdn.tinymce.com/) - February 25th 2021
  • Tiny Cloud (https://cloud.tinymce.cloud/ & https://cdn.tiny.cloud/) - February 25th 2021

To assist you with migrating from TinyMCE 4 to TinyMCE 5, we’ve put together a simple 4-stage, step-by-step process that will help with most migrations:

  1. Update the core editor
  2. Review themes and editing modes
  3. Consider core plugin changes
  4. Review any advanced configurations

For more information, refer to the migration guide in the Tiny docs.

1. Update the core editor

In many cases, migrating from TinyMCE 4 to TinyMCE 5 is as simple as updating the source of the TinyMCE script file in your HTML pages (replacing no-api-key with your own API key from your Tiny account dashboard):

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

For example, see the following HTML files and the resulting editor instance for each, with the only difference being the source of the TinyMCE script file.

TinyMCE 4

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <strong><script src="https://cloud.tinymce.com/stable/tinymce.min.js"></script></strong>
    <script>
      tinymce.init({
        selector: "#mytextarea"
      });
    </script>
  </head>
  <body>
    <h1>TinyMCE Quick Start</h1>
    <form method="post">
      <div id="mytextarea">Hello, World!</div>
    </form>
  </body>
</html>
Default TinyMCE 4 configuration.

TinyMCE 5

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <strong><script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/5/tinymce.min.js" referrerpolicy="origin"></script></strong>
    <script>
      tinymce.init({
        selector: "#mytextarea"
      });
    </script>
  </head>
  <body>
  <h1>TinyMCE Quick Start</h1>
    <form method="post">
      <div id="mytextarea">Hello, World!</div>
    </form>
  </body>
</html>
Default TinyMCE 5 configuration.

2. Review themes and editing modes

All themes provided with TinyMCE 4 have been removed. In TinyMCE 5, there is a single, modern, and responsive theme called Silver that is enabled by default.

Previously, themes were also used as a way of configuring different modes of the editing experience, like inlite and mobile; however, these are now separate configuration options of their own.

TinyMCE 4

In TinyMCE 4, you may have had a theme specified in your configuration:

tinymce.init({
  selector: "#mytextarea",
  theme: "modern"
});

TinyMCE 5

In TinyMCE 5, you can either provide the silver theme, or simply remove the theme option from the config altogether; for example:

tinymce.init({
  selector: "#mytextarea",
  theme: "silver"
});

Inline mode

TinyMCE 5 inline editing.

In both TinyMCE 4 & TinyMCE 5, inline mode is configured by setting the inline option to true:

tinymce.init({
  selector: "#mytextarea",
  inline: true
});

Read more information about inline mode.

Inlite/distraction-free mode

TinyMCE 5 distraction-free editing.

TinyMCE 4

In TinyMCE 4, the distraction-free inlite mode was configured with the following settings:

tinymce.init({
  selector: "#mytextarea",
  inline: true,
  theme: "inlite"
});

TinyMCE 5

In TinyMCE 5, the same distraction-free mode is configured with the new quickbars plugin. The following TinyMCE 5 configuration will replicate the same behavior as the default inlite configuration above:

tinymce.init({
  selector: "#mytextarea",
  inline: true,
  plugins: "quickbars",
  toolbar: false,
  menubar: false
});

Note that the quickbars plugin allows for more flexibility - it can be used in the regular or inline modes, with or without the menu bar or toolbar.

It’s also important to note that if you have customized the inlite menu options using selection_toolbar or insert_toolbar, you’ll also need to change these to quickbars_selection_toolbar and quickbars_insert_toolbar, respectively.

Read more information about distraction-free mode.

Mobile mode

Horizontal scrolling toolbar and menus for tables on Tiny mobile.

With the release of TinyMCE 5.1, came a complete mobile-first redesign of TinyMCE, significantly better than the previous mobile experience. With the responsive design, there is typically no need for a separate mobile option - the mobile UX is applied automatically to suit the device used - and almost all 50+ plugins are supported, compared to only three plugins previously. Read more about the features and benefits of TinyMCE mobile.

TinyMCE 4

In TinyMCE 4, the mobile experience was configured with a specific mobile option:

tinymce.init({
  selector: "#mytextarea",
  mobile: {
    theme: "mobile"
  }
});

TinyMCE 5

If you were previously using the mobile theme, we strongly recommend removing the mobile option from your configuration and trying the new, mobile-first design.

You can still use the mobile option to override the default mobile experience with your own specific settings if required (including reverting back to the legacy mobile theme - but with support for only the three plugins as before).

Read more about configuring TinyMCE mobile.

3. Consider core plugin changes

In TinyMCE 5, the contextmenu, textcolor, and colorpicker plugins are included in the core editor and do not need to be loaded explicitly using the plugins option.

If they remain in your list of loaded plugins, TinyMCE will only raise a warning. However, take note of the changes to their corresponding config options, shown below.

contextmenu

TinyMCE 5 context menu.

TinyMCE 4

In TinyMCE 4, the context menu was enabled by loading it as a plugin to support any plugins that made use of it, for example, the link plugin:

tinymce.init({
  selector: "#mytextarea",
  plugins: "link contextmenu"
});

TinyMCE 5

In TinyMCE 5, the context menu is included with the core editor and enabled by default when relevant plugins are loaded. To remove it, set it to false:

tinymce.init({
  selector: "#mytextarea",
  plugins: "link",
  contextmenu: false
});

textcolor

TinyMCE 5 default color picker.

TinyMCE 4

In TinyMCE 4, there were three options used to configure the color pallette - textcolor_cols, textcolor_rows, textcolor_map - for example:

tinymce.init({
  selector: "#mytextarea",
  plugins: "textcolor",
  toolbar: "forecolor",
  textcolor_cols: "3",
  textcolor_rows: "3",
  textcolor_map: [
    "993366",
    "Red violet",
    "FFFFFF",
    "White",
    "FF99CC",
    "Pink",
    "FFCC99",
    "Peach",
    "FFFF99",
    "Light yellow",
    "CCFFCC",
    "Pale green",
    "CCFFFF",
    "Pale cyan",
    "99CCFF",
    "Light sky blue",
    "CC99FF",
    "Plum"
  ]
});

TinyMCE 5

In TinyMCE 5, there are only two (renamed) options - color_cols and color_map - with the number of rows calculated automatically. For example, the following config is the version 5 equivalent:

tinymce.init({
  selector: "#mytextarea",
  toolbar: "forecolor",
  color_cols: "3",
  color_map: [
    "993366",
    "Red violet",
    "FFFFFF",
    "White",
    "FF99CC",
    "Pink",
    "FFCC99",
    "Peach",
    "FFFF99",
    "Light yellow",
    "CCFFCC",
    "Pale green",
    "CCFFFF",
    "Pale cyan",
    "99CCFF",
    "Light sky blue",
    "CC99FF",
    "Plum"
  ]
});

colorpicker

TinyMCE 4

In TinyMCE 4, the option to select a custom color from a color picker, when using the textcolor plugin, was configured by adding the colorpicker plugin:

tinymce.init({
  selector: "#mytextarea",
  plugins: "textcolor colorpicker",
  toolbar: "forecolor backcolor"
});

TinyMCE 5

In TinyMCE 5, the color picker is included with the core editor and enabled by default. It can be disabled using the new custom_colors option:

tinymce.init({
  selector: "#mytextarea",
  toolbar: "forecolor backcolor",
  custom_colors: false
});

Other name changes

If you’re using the autoresize plugin:

  • autoresize_min_height is now min_height
  • autoresize_max_height is now max_height

Height and width settings have been removed from plugin dialogs, with the following options removed from these plugins:

  • code plugin - code_dialog_height and code_dialog_width
  • codesample plugin - codesample_dialog_height and codesample_dialog_width
  • preview plugin - plugin_preview_height and plugin_preview_width
  • template plugin - template_popup_height and template_popup_width

4. Review any advanced configurations

If you are making use of advanced UI configuration methods and configuration settings, including custom UI components such as toolbar buttons, context toolbars, menu items, or dialogs, read more about the changes to UI components and configuration settings.

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

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.

What next?

For more information about migrating to TinyMCE, refer to the migration guide. If you’re migrating to the cloud from a self-hosted configuration, also refer to our cloud deployment guide.

Apply skins and icons from the most popular design systems, available with our skins and icon packs. Or design your own using our TinyMCE skin tool. More information about creating your own skin is available in our Tiny docs.

TinyMCE 5 comes with a simplified pricing option for our premium features (such as our most popular PowerPaste plugin) and access to support which may be helpful as you migrate. Start with a free 14-day trial.

Contact us for more assistance migrating to TinyMCE 5 or for more information about any of our premium plugins.

TinyMCE with custom skin and icons, and toolbar options grouped on the bottom.
ConfigurationMigration
Ben Long
byBen Long

Developer Advocate at Tiny. Computer scientist turned storyteller. Reminisces about programming on the MicroBee. Writes picture books for kids. Also the wearer of rad shoes. “Science isn’t finished until you share the story.”

Related Articles

  • A crystal ball on top of illuminated squares.
    How-tos & Tutorials

    TinyMCE CSS and custom styles

    by Ben Long in How-tos & Tutorials
  • Text that reads "<!DOCTYPE HTML>".
    How-tos & Tutorials

    TinyMCE requires standards mode

    by Ben Long in How-tos & Tutorials
Subscribe for the latest insights served straight to your inbox. Delivered weekly.

Deploy TinyMCE in just 6 lines of code

Built to scale. Developed in open source. Designed to innovate.

Begin with your FREE API Key
Tiny Editor