Migration from CKEditor 4

This section of the documentation explains how to migrate to CKEditor 5.

When compared to its predecessor, you should treat CKEditor 5 as a totally new editor. We have redesigned every single aspect of it – from installation, to integration, to features, to its data model, and finally to its API.

There is no automatic solution for migrating. This section summarizes the most important aspects you need to consider before you proceed with moving to CKEditor 5.

# Differences between CKEditor 4 and CKEditor 5

What differentiates CKEditor 5 from its predecessor the most is its core architecture. CKEditor 5 is a highly flexible and extensible editing framework with a powerful API. You can use it to create any WYSIWYG editor implementation, from a lightweight chat to a complex Google Docs-like solution. CKEditor 5 is also collaboration-ready and offers features such as real-time collaboration, comments, or track changes.

Here are the key differences between the two editor versions:

	CKEditor 4	CKEditor 5
Programming language	JavaScript	TypeScript
Data model	HTML/DOM	Custom data model and virtual DOM implementation
Architecture	Plugin-based	Plugin-based, MVC
Editor types	Classic, inline	Classic, inline, decoupled (document), balloon, balloon block, multi-root
Collaboration-ready	❌	✅
File management and image upload	CKFinder	CKBox, CKFinder
UI	Toolbar, dialogs, and features manipulated through right-click context menu	Toolbar, dropdowns, balloons, and features manipulated through on-click feature toolbars
UI customization	Skins, UI color change	Themes, customization with CSS variables
License	GPL, MPL, LGPL, commercial license	GPL 2+ or commercial license

# Feature comparison of CKEditor 4 and CKEditor 5

Digital content editing paradigms have changed a lot between the times of CKEditor 4 and now. We designed and built CKEditor 5 from scratch, taking into account the possibilities of modern web apps, current web standards, and the needs of today’s users.

This new approach affects the available feature set, how features were implemented, and what configuration options are available for them. To make it easier to compare both editor versions, we have created the following compatibility tables:

• CKEditor 4 plugin equivalents
• CKEditor 4 configuration options compatibility

You can use them to check the CKEditor 5 equivalents of some features or configuration options from CKEditor 4. If there is no direct equivalent, the tables will point you to a solution recommended in CKEditor 5. We strongly advise you to treat the migration to CKEditor 5 as an opportunity to modernize your application and rethink your editing solutions.

# Before you migrate

CKEditor 4 and CKEditor 5 are two different products. Here are the most important aspects you need to consider before you migrate.

# Migrating existing data

Perform extensive analysis, data verification, and tests on existing data. If necessary, you will need to develop conversion procedures to avoid data loss. You can use the General HTML Support feature to introduce HTML markup that is present in the legacy content but is not yet fully covered by CKEditor 5 features.

The Plugins and HTML output article lists all official CKEditor 5 plugins and the HTML output they produce. You can use it to check the compatibility of legacy data with what is supported in CKEditor 5.

A simple yet efficient strategy for adopting CKEditor 5 into existing systems might be using CKEditor 5 for creating new content and the old editor for editing legacy content.

# Installation and integration

The first aspect that changed with CKEditor 5 is its installation procedure. It became much more modern with the introduction of modular patterns, UMD, npm, etc. Refer to the Getting started section to explore all available installation and integration options.

The API for integrating CKEditor with your pages changed, too. Check the Editor lifecycle and Getting and setting data articles for an introduction to this topic.

# Custom plugins

Any custom plugins you have developed for CKEditor 4 will not be compatible with CKEditor 5. Although their idea may stay the same, their implementation will certainly be different and will require rewriting them from scratch.

The same may apply to third-party plugins. They may not have been ported to CKEditor 5 yet.

Check the Creating plugins section for more information on the development of plugins.

# Custom themes (skins)

In CKEditor 5, the earlier concept of “skins” was reviewed and is now called “themes.”

If you have custom skins for CKEditor 4, you need to re-create them for CKEditor 5. Fortunately, custom theming in CKEditor 5 is much more powerful and simpler than before.

What’s new: you can use CKEditor 5 as a headless editor integrated with an external UI, for example, created in React. Many projects use the powerful editing engine of CKEditor 5 coupled with a custom UI for seamless integration with their application.

For more information, check how to customize the themes in the CKEditor 5 Framework documentation.

# Image upload

CKEditor 5 supports several different image upload strategies. Check out the comprehensive “Image upload” guide to find out the best option for your project.

# License

CKEditor 4 was licensed under GPL, LGPL, and MPL Open Source licenses.

CKEditor 5 is licensed under GPL2+ Open Source license only. If you are running an Open Source project under an OSI-approved license incompatible with GPL, we will be happy to support you with a no-cost license. If your project is a commercial one, you will need to get a commercial license.

# Recommended migration strategy

You can approach moving from CKEditor 4 to CKEditor 5 as follows:

1. Back up all your data.
2. Learn about CKEditor 5. Check the demos, read about its architecture, and review the available features and integration methods.
3. Create a custom preset containing all the plugins you need the Builder.
4. Test loading pre-existing content created in CKEditor 4 into CKEditor 5. Adjust the editor configuration and plugin set. If needed, enable the missing elements, classes, or attributes via the General HTML Support feature.
5. When you are sure no data loss will occur, you can focus on customizing your CKEditor 5 preset even more by changing the integration method, creating custom plugins, adjusting the theme, and enabling new features.

CKEditor 5 is a great, modern editing framework so migrating is a fantastic opportunity to level your content editing experience up. Collaboration with real-time collaborative editing, comments and track changes, revision history, autoformatting, import from Word, export to PDF and Word, word and character count, and CKBox file manager are just a few examples of new features that were not available in CKEditor 4. Try them out!

# Support

If you are missing any particular features or settings, feel free to report an issue. Search the issues section in the repository first. The feature you are after may have already been reported – you can support it by upvoting the issue with  👍. Be as precise as possible, explaining the exact use case, the context where you use the editor, and the expected behavior.

The Troubleshooting migration from CKEditor 4 article answers some frequently asked questions about the migration.

Contact the support team if you want to learn more about licensing or the Extended Support Model.