Migrating from TinyMCE 4 to TinyMCE 7.0

Overview

TinyMCE has evolved significantly from version 4 to version 7.0, introducing major architectural changes, modern UI improvements, enhanced performance, and better security. This guide outlines the critical breaking changes, recommended migration action steps, and top-level configuration adjustments required to upgrade from TinyMCE v4 to v7.0.

Key Changes

UI Themes and Skins

  • Removed: modern, lightgray, and mobile themes/skins.

  • New: silver theme with oxide skin (supports light and dark variants). see customize-ui.

  • Impact: Custom v4 skins/themes are incompatible with v7.0 and must be rewritten using the oxide skin structure.

Example:
tinymce.init({
  selector: "textarea",
  skin: "oxide-dark",
  content_css: "dark",
});

Plugin Ecosystem

The TinyMCE plugin ecosystem was significantly restructured in version 6.0, with several plugins being removed, folded into the TinyMCE Core (Open Source), or reclassified as premium features. The following breakdown clarifies the status of each affected plugin.

  • Removed Plugins (no longer available as of TinyMCE 6.0):

    • bbcode, fullpage, legacyoutput: Deprecated in 5.9.0. Removed in 6.0.

  • Integrated into TinyMCE Core (Open Source):

    • paste, hr, noneditable, table, print, colorpicker and contextmenu: These plugins were absorbed into TinyMCE Core (Open Source) and no longer require separate installation.

    • contextmenu: Deprecated in version 5.0 following the integration of context menu functionality into TinyMCE Core (Open Source) editor. Removed in version 6.0. For more information, see the contextmenu documentation.

    • tabfocus: Removed in 6.0. Keyboard navigation via Tab is now handled by the browser and TinyMCE Core (Open Source).

  • Now Premium Only:

    • mediaembed, tableofcontents: These features are available through premium plugins.

    • spellchecker: Deprecated in 5.9.0. Removed in 6.0.

      • Use browser_spellcheck: true or the premium Spell Checker plugin.

    • template: Removed in 7.0. Replaced by the premium Templates plugin.

    • imagetools: Removed in 6.0. Replaced by the premium Enhanced Image Editing feature, available via the editimage plugin introduced in TinyMCE 6.0.

Plugin Migration Tips

  • contextmenu (removed in v6):

  • bbcode (removed in v6):

    • Implement custom parsing or server-side processing if BBCode support is required.

  • fullpage (removed in v6):

    • Use custom templates or server-side logic to handle full HTML documents.

  • template (removed in v7.0):

    • Use the premium advtemplate plugin or implement custom modal dialogs.

  • textcolor (removed in v6):

    • Use the forecolor and backcolor toolbar buttons for text color functionality.

  • imagetools: (removed in v6):

Toolbar and Menu name changes

If you used the following toolbar buttons or menu options, they have changed names across major TinyMCE versions. Please refer to the release notes for each version for complete migration details.

TinyMCE 5 → TinyMCE 6:

  • formatselect → blocks (toolbar item)

  • blockformats → blocks (menu item)

  • styleselect → styles (toolbar item)

  • formats → styles (menu item)

  • fontselect → fontfamily (toolbar item)

  • fontformats → fontfamily (menu item)

  • fontsizeselect → fontsize (toolbar item)

  • fontsizes → fontsize (menu item)

  • imagetools → editimage (plugin and related toolbar items)

  • toc → tableofcontents (plugin, menu item, and toolbar item)

  • tocupdate → tableofcontentsupdate (toolbar item)

TinyMCE 6 → TinyMCE 7:

  • InsertOrderedList and InsertUnorderedList commands were removed from TinyMCE Core (Open Source) and are now provided by the lists plugin.

  • Default text pattern triggers were updated to activate on Space instead of Enter. A trigger property was added to configure block-level text pattern behavior.

Refer to the latest release notes at latest release notes for further details.

Always refer to the latest plugin documentation at plugins for up-to-date availability and migration guidance.
Example of Toolbar Changes:
tinymce.init({
  selector: "textarea",
  toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify",
  plugins: ["lists link image table code"]
});

Content Structure

  • Removed: forced_root_block: false.

    • Requirement: All editor content must be enclosed in block elements (e.g., <p>).

Example:
tinymce.init({
  selector: "textarea",
  forced_root_block: "p"
});

Configuration Changes

  • Removed in TinyMCE 6.0: Legacy mobile theme was removed, but mobile-specific configuration is still supported through the mobile option.

  • Default Changes in TinyMCE 7.0:

  • New Options in TinyMCE 7.0:

Example:
tinymce.init({
  selector: "textarea",
  toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat",
  toolbar_mode: "floating",
  // Required in TinyMCE 7.0 if self-hosting
  license_key: "gpl",
  // Security options now enabled by default in TinyMCE 7.0
  sandbox_iframes: true,
  convert_unsafe_embeds: true,
  // Optional: exclude specific domains from iframe sandboxing
  sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"],
  // Accessibility improvement, now enabled by default
  highlight_on_focus: true
});

Licensing Changes (GPL v2+ and Commercial)

  • Legacy License: TinyMCE 4 was licensed under LGPL 2.1.

  • New License: TinyMCE 7.0 is licensed under GPL v2+ or a commercial license.

  • Impact: The License key option is required as part of your editor configuration if self-hosting TinyMCE. This requirement does not apply if you are loading TinyMCE from the cloud.

Example:
tinymce.init({
  selector: "textarea",
  license_key: "your-license-key"
});

Migration Tips

  1. Backup and Prepare: Ensure comprehensive backups before upgrading.

  2. Update Core Initialization:

    1. Update theme, skin, and to refect the new oxide theme and skin.

      1. In TinyMCE 4, there were multiple themes available including 'modern', 'inlite', and 'mobile'. These themes were removed in TinyMCE 5 and combined into a single responsive theme called "Silver".

    2. Update forced_root_block: false options to forced_root_block: "p".

    3. Consolidate toolbars.

    4. Review new v7.0 defaults for security settings.

  3. Plugin Migration:

    1. Remove deprecated plugins from your configuration.

    2. Update renamed plugins (e.g., spellchecker → tinymcespellchecker).

    3. Verify premium plugins for compatibility.

  4. Custom Code Updates:

    1. Rewrite custom plugins using the editor.ui.registry.* API. see editor.ui.registry.

    2. Replace v4 API methods like editor.addButton, editor.addMenuItem, editor.windowManager.open.

    3. Update media embed handling (media_url_resolver API changes). see media_url_resolver.

  5. CSS Updates:

    1. Update custom styles to align with the new Oxide standard. While many .mce-* classes have been replaced with .tox-* classes, some .mce-* prefixes remain in use. Review your CSS to ensure compatibility.

  6. Testing and Deployment:

    1. Thoroughly test your updated configuration before production deployment.

    2. Validate media, iframe, and content security settings.

Additional Resources

To make your upgrade smooth, check the following version-specific migration guides:

These include deeper configuration notes, plugin replacements, and examples.

Next Steps

Ensure you follow the migration steps carefully to avoid common issues like missing plugins, broken UI, and unexpected formatting changes. Consider running your updated editor in a staging environment for a complete verification before final deployment.

OSZAR »