Migrating from TinyMCE 5 to TinyMCE 7.0

Overview

TinyMCE has evolved significantly from version 5 to version 7.0, introducing architectural improvements, modern UI enhancements, stricter security defaults, and updated plugin structures. This guide outlines the critical breaking changes, recommended migration action steps, and top-level configuration adjustments required to upgrade from TinyMCE v5 to v7.0.

Key Changes

UI Themes and Skins

  • Minor Adjustments: Oxide-based skins from v5 remain mostly compatible but may require small CSS adjustments for v7.0.

  • Impact: Test custom skins visually, as minor DOM changes can affect layout and styling.

  • Browser Support: Internet Explorer 11 is no longer supported in v7.0 (dropped in v6), requiring modern browsers.

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

Plugin Ecosystem

The TinyMCE plugin ecosystem underwent a significant overhaul starting in version 6.0, with many plugins either removed, integrated into the core, or made premium-only. The following summarizes these changes.

  • 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, table, noneditable, nonbreaking, 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.

    • toc: Renamed to tableofcontents and now premium.

    • advtemplate: Replaces the template plugin for advanced templating use cases.

Plugin Migration Examples

  • 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.

  • UI API Updates:

    • Update custom plugins to use editor.ui.registry.*.

    • Replace deprecated methods like editor.addButton, editor.addMenuItem, and editor.windowManager.open.

  • Promise-Based Methods:

    • media_url_resolver now requires a Promise return for asynchronous handling.

  • Removed Options:

    • force_hex_color has been removed. Use standard CSS color declarations.

    • table_responsive_width replaced by table_sizing_mode.

  • 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",
  license_key: "gpl", // Required in TinyMCE 7.0 if self-hosting
  // 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
});
For up-to-date plugin availability and configuration references, see link:https://www.tiny.cloud/docs/plugins/.

Refer to version-specific release notes for changes in toolbar button names and command availability across versions 5, 6, and 7. For example:

TinyMCE 5 → TinyMCE 6:

  • formatselect → blocks

  • styleselect → styles

  • fontselect → fontfamily

  • fontsizeselect → fontsize

  • imagetools → editimage

  • toc → tableofcontents

TinyMCE 6 → TinyMCE 7:

  • InsertOrderedList / InsertUnorderedList commands removed from TinyMCE Core (Open Source) (use lists plugin).

  • Default text pattern triggers updated from Enter to Space, configurable via trigger.

Licensing Changes (GPL v2+ and Commercial)

  • Legacy License: TinyMCE 5 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.

    2. Replace v5 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.