Migration from CKEditor 4

If you are moving from CKEditor 4 to CKEditor 5, this guide is your starting point. CKEditor 5 was rebuilt from the ground up - from installation and integration to its data model and APIs. It is a genuinely new editor rather than a new version of the old one. Therefore, there is no automatic migration path. The sections below explain the key differences between versions and what you need to plan for before you start.

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:

Beyond the editor types, CKEditor 5 gives you control over the editable element itself. In non-classic editors, config.root.element accepts a tag name or an element definition with classes, attributes, and inline styles, so the editable can be a semantic element such as an <h1> rather than the default <div>. The <textarea> and <input> elements are not supported. A root can also use the $inlineRoot model element, which permits inline content only and turns the editable into a paragraph-like area suitable for titles, labels, and other single-line fields. Refer to the Root types guide for details.

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.

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

Perform extensive analysis, data verification, and tests on existing data. If necessary, you will need to develop conversion procedures to avoid data loss.

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

CKEditor 5 maps several presentational constructs common in CKEditor 4 content onto its own features, as long as the matching plugin is part of your setup:

Your own configuration takes precedence over these mappings. If you define custom image styles, for example, they take precedence over the float style.

CKEditor 4 indented list items by nesting them in sublists, and CKEditor 5 reads that structure directly. The editor also recognizes margin-left on <li> elements, which helps with content pasted from word processors.

Two constructs need to be enabled explicitly, because the editor discards them by default:

• Table footers. Set config.table.enableFooters to true to keep <tfoot> elements. Footer rows are ignored otherwise.
• Lists that skip nesting levels. Set config.list.enableSkipLevelLists to true to preserve non-sequential indentation levels.

Some CKEditor 4 markup does not map onto a CKEditor 5 feature and needs attention before or during the migration:

For everything that remains, use the General HTML Support feature to keep elements, classes, and attributes that are present in the legacy content but are not covered by the CKEditor 5 features you enabled.

If your legacy content includes <script> tags that worked in CKEditor 4, see the Enabling script tags for legacy use cases section in the General HTML Support guide.

Legacy <iframe> embeds are subject to two restrictions in the editing view:

• Every iframe receives a sandbox attribute, which blocks scripts, forms, and popups while editing. Set config.htmlSupport.htmlIframeSandbox to an array of sandbox flags to permit selected capabilities, or to false to turn the enforcement off.
• The srcdoc attribute is never rendered, and you cannot change this behavior.

Both restrictions apply to the editing view only. Calling editor.getData() returns your iframes unchanged, so keep enforcing iframe sandboxing in your own sanitization pipeline.

CKEditor 5 wraps block-level widgets in a <figure> element. A table that CKEditor 4 stored as a bare <table> becomes <figure class="table"> with the <table> inside it, so make sure your style sheets, templates, and server-side processing handle this wrapper. If your system requires plain table markup, for example when generating email, add the PlainTableOutput plugin to remove the <figure> wrapper from the table data.

Images are a mixed case. Captioned images created with the enhanced image plugin in CKEditor 4 already used <figure class="image">, which is what CKEditor 5 uses as well, so they convert without changes. Images without captions were plain <img> elements and gain the <figure> wrapper when the editor loads them as block images.

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.

The first aspect that changed with CKEditor 5 is its installation procedure. Instead of dropping a single script into your page, you install CKEditor 5 from npm, load it from the CDN, or download it as a ZIP package. 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.

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.

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.

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

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.

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 using 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!

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.