Migration from CKEditor 4

Migration from CKEditor 4

When compared to its predecessor, CKEditor 5 should be considered a totally new editor. Every single aspect of it was redesigned — from installation, to integration, to features, to its data model, and finally to its API. Therefore, moving applications using a previous CKEditor version to version 5 cannot be simply called an “upgrade”. It is something bigger, so the “migration” term fits better.

There is no “drop in” solution for migrating. In this guide we hope to summarize the most important aspects you need to consider before you proceed with installing CKEditor 5.

Before starting, be sure that migrating is your best choice. Refer to When NOT to use CKEditor 5 Builds? for more information.

Installation and integration

The very 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 Installation for more details.

The API for integrating CKEditor with your pages also changed. It is worth checking Basic API for an introduction.

Features

When it comes to features, there are two aspects that need to be taken into consideration:

CKEditor 5 may still not have the same features available as CKEditor 4.
Existing features may behave differently. Therefore, it is worth spending some time analyzing required features.

CKEditor 5 was designed with focus on creating quality content. There are thus good reasons for it to not support some old features. You should take this chance to rethink the features available in your application and perhaps switch the approach towards a more modern reasoning.

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.

Plugins

The trickiest migration challenge to be faced may be related to custom plugins you have developed for CKEditor 4. Although their concept may stay the same, their implementation will certainly be different and will require rewriting them from scratch.

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

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

Themes (skins)

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

If you have custom skins for CKEditor 4, these skins need to be recreated for CKEditor 5. Fortunately, custom theming in CKEditor 5 is much more powerful and simpler than before.

Existing data

An extremely important aspect to be remembered is that — because of the difference in features — the data produced with CKEditor 4 may not be compatible with CKEditor 5 (which may lead to data loss).

Extensive analysis, data verification and tests should be performed on existing data. If necessary, you will need to develop conversion procedures to avoid data loss. A relatively simple yet efficient strategy of adopting CKEditor 5 into existing systems might be using CKEditor 5 for creating new content and the old editor for editing legacy content.

Configuration options compatibility table

The following table presents configuration options available in CKEditor 4 and their equivalent in CKEditor 5.

Note: The number of options was reduced on purpose. We understood that configuring CKEditor 4 was a bit too troublesome due to the number of configuration options available (over 240). Sometimes they were definitely too low-level, also many times they were so infrequently used that it did not justify the increased level of the application complexity. This is why when designing CKEditor 5 from scratch, we decided to come with a simplified editor, with well-thought default behavior, based on the results of the Editor Recommendations project.

CKEditor 4	CKEditor 5
allowedContent	Extending the list of HTML tags or attributes that CKEditor should support can be achieved by writing a plugin that (ideally) provides also means to control (insert, edit, delete) such markup. For more information on how to create plugins check the Creating a simple plugin article. Looking at the source code of CKEditor 5 plugins may also give you a lot of inspiration.
autoEmbed_widget	Media embedding is not supported yet, but it is planned.
autoGrow_bottomSpace autoGrow_maxHeight autoGrow_minHeight autoGrow_onStartup	Classic editor (CKEditor 5) no longer encapsulates the editing area in an `<iframe>`, which means that the height (and similar options) of the editing area can be easily controlled with CSS. For example the `minHeight` and `maxHeight` settings can be achieved with `.ck-editoreditable_inline { min-height:200px; max-height:400px; }`. See also How to set the height of CKEditor 5 (Classic editor).
autoUpdateElement	CKEditor 5 always updates the replaced element. This behavior cannot be disabled.
baseFloatZIndex	N/A. There is a dedicated issue about z-index management and making it more open for developers.
baseHref	Not supported yet, see https://github.com/ckeditor/ckeditor5/issues/665.
basicEntities	N/A
blockedKeystrokes	N/A
bodyClass	Classic editor (CKEditor 5) no longer encapsulates the editing area in an `<iframe>`, so such setting is no longer needed. Simply wrap the editor with a `<div class="…">` to achieve a similar result. When using Balloon or Inline editor you may add a class to the element on which the editor is initialized.
bodyId	Classic editor (CKEditor 5) no longer encapsulates the editing area in an `<iframe>`, so such setting is no longer needed. Simply wrap the editor with a `<div id="…">` to achieve a similar result. When using Balloon or Inline editor you may add a class to the element on which the editor is initialized.
browserContextMenuOnCtrl	No longer needed as CKEditor 5 does not have its own context menu and does not block the native browser context menu.
clipboard_defaultContentType clipboard_notificationDuration	N/A
codeSnippetGeshi_url codeSnippet_codeClass codeSnippet_languages codeSnippet_theme	Code blocks are not supported yet. A plugin adding support for the inline `<code>` element is already included in the Basic styles package. Note: The Code feature is not available by default in any build, but can be enabled in a custom build.
colorButton_backStyle colorButton_colors colorButton_colorsPerRow colorButton_enableAutomatic colorButton_enableMore colorButton_foreStyle colorButton_normalizeBackground	The “classic” font/background color feature will be provided in the future. At the same time, we already provide a new Highlight plugin which allows for highlighting parts of the text with the `<mark>` element with different CSS classes that can be easily styled. See the Highlight feature guide for more information .
contentsCss	Classic editor (CKEditor 5) no longer encapsulates the editing area in an `<iframe>`, so such file and configuration setting is no longer needed. If for some reason you need to style the contents of the editing area differently, use the `.ck-content` selector.
contentsLangDirection	In case of Inline or Balloon editor, just add the `dir` attribute to the edited element. In case of Classic editor, see https://github.com/ckeditor/ckeditor5/issues/671.
contentsLanguage	In case of Inline or Balloon editor, just add the `lang` attribute to the edited element. In case of Classic editor, see https://github.com/ckeditor/ckeditor5/issues/670.
copyFormatting_allowRules copyFormatting_allowedContexts copyFormatting_disallowRules copyFormatting_keystrokeCopy copyFormatting_keystrokePaste copyFormatting_outerCursor	N/A
coreStyles_bold	CKEditor 5 uses the `<strong>` element, see Editor Recommendations - Bold.
coreStyles_italic	CKEditor 5 uses the `<i>` element, see Editor Recommendations - Italic.
coreStyles_strike	CKEditor 5 uses the `<s>` element, see Editor Recommendations - Strikethrough.
coreStyles_subscript coreStyles_superscript	Planned.
coreStyles_underline	CKEditor 5 uses the `<u>` element, see Editor Recommendations - Underline. Note: The Underline feature is not available by default in any build, but can be enabled in a custom build (see the Basic styles feature guide).
customConfig	For performance reasons, CKEditor 5 no longer loads a separate configuration file. Passing configuration options inline reduces the number of HTTP requests.
dataIndentationChars	N/A
defaultLanguage	The support for multiple translations is handled by the translations service. See features/ui-language
devtools_styles devtools_textCallback	N/A
dialog_backgroundCoverColor dialog_backgroundCoverOpacity	The use of configuration options to style selected parts of the editor was dropped in favor of much more powerful theme customization.
dialog_buttonsOrder dialog_magnetDistance dialog_noConfirmCancel dialog_startupFocusTab	N/A
disableNativeSpellChecker	Unavailable, however, in case of inline and balloon editors can be done by setting the `spellcheck` attribute directly on the element where CKEditor should be enabled. For the classic and decoupled editors, call: `editor.editing.view.change( writer => {` `writer.setAttribute( 'spellcheck', 'false', editor.editing.view.document.getRoot() );` `} );`
disableNativeTableHandles	N/A
disableObjectResizing	N/A
disableReadonlyStyling	N/A
disallowedContent	N/A
div_wrapTable	N/A
docType	N/A. CKEditor 5 no longer encapsulates the editing area in an `<iframe>`, so the editor is using the same doctype as the page where it operates.
emailProtection	N/A
embed_provider	N/A
enableContextMenu	N/A. CKEditor 5 does not come with a context menu, contextual inline toolbar is preferred instead to offer contextual actions.
enableTabKeyTools	N/A
enterMode	N/A. CKEditor 5 always creates a new paragraph (`<p>` element) as specified by Editor Recommendations - Enter key. `Shift` + `Enter` support is handled in https://github.com/ckeditor/ckeditor5-enter/issues/2.
entities entities_additional entities_greek entities_latin entities_processNumerical	N/A
extraAllowedContent	See `config.allowedContent`.
extraPlugins	Enabling extra plugins is possible by creating a custom build.
fileTools_defaultFileName	N/A
filebrowserBrowseUrl filebrowserFlashBrowseUrl filebrowserFlashUploadUrl filebrowserImageBrowseLinkUrl filebrowserImageBrowseUrl filebrowserImageUploadUrl filebrowserUploadUrl filebrowserWindowFeatures filebrowserWindowHeight filebrowserWindowWidth	There is no equivalent of the file browser plugin in CKEditor 5 yet. See also `config.uploadUrl`.
fillEmptyBlocks	N/A
find_highlight	N/A
flashAddEmbedTag flashConvertOnEdit flashEmbedTagOnly	N/A
floatSpaceDockedOffsetX floatSpaceDockedOffsetY floatSpacePinnedOffsetX floatSpacePinnedOffsetY floatSpacePreferRight	N/A
fontSize_defaultLabel fontSize_sizes fontSize_style font_defaultLabel font_names font_style	See the Font feature guide.
forceEnterMode	N/A. Se also `config.enterMode`.
forcePasteAsPlainText	N/A. No longer needed as CKEditor 5 removes all unwanted markup that cannot be edited with the editor.
forceSimpleAmpersand	N/A
format_address format_div format_p format_pre	N/A
format_h1 format_h2 format_h3 format_h4 format_h5 format_h6	All headings are configurable via `heading.options`. See also the Headings feature guide.
format_tags	N/A. In order to enable additional block tags in CKEditor 5 a dedicated plugin must be provided. See also `config.allowedContent`.
fullPage	N/A
grayt_autoStartup	N/A. There is no grammar checking plugin in CKEditor 5 at this moment. However, the native browser spell checker can be used in CKEditor 5.
height	Classic editor (CKEditor 5) no longer encapsulates the editing area in an `<iframe>`, which means that the height (and similar options) of the editing area can be easily controlled with CSS. For example the height setting can be achieved with `.ck-editoreditable_inline { height:400px; }`. See also How to set the height of CKEditor 5 (Classic editor).
htmlEncodeOutput	N/A. CKEditor 5 outputs HTML markup. See also https://stackoverflow.com/questions/47555667/ckeditor-5-htmlencodeoutput-doesnt-work and a dedicated issue.
ignoreEmptyParagraph	N/A
image2_alignClasses	Available via more powerful `image.styles`. This also allows for using custom style definitions, not only left, right and center alignment. See the Image styles feature overview.
image2_altRequired image2_captionedClass image2_disableResizer image2_prefillDimensions.	N/A
imageUploadUrl	See `config.uploadUrl`.
image_prefillDimensions image_previewText image_removeLinkByEmptyURL	N/A
indentClasses indentOffset indentUnit	N/A
jqueryOverrideVal	N/A
justifyClasses	See text alignment feature guide.
keystrokes	Keystroke handlers can be registered using `EditingKeystrokeHandler`. More information and examples can be found in a dedicated Keystrokes and focus management section. Making keystrokes overridable through `config.keystrokes` is handled in a dedicated issue. There is also an issue about improving keystroke handling.
language language_list	See `config.uploadUrl`.
linkJavaScriptLinksAllowed	N/A
linkShowAdvancedTab linkShowTargetTab	N/A
magicline_color magicline_everywhere magicline_holdDistance magicline_keystrokeNext magicline_keystrokePrevious magicline_tabuList magicline_triggerOffset	N/A. The magic line feature itself is planned.
mathJaxClass mathJaxLib	N/A
menu_groups menu_subMenuDelay	N/A
newpage_html	N/A
notification_duration	N/A
on	Using the configuration file or setting to define event listeners was a bad practice so support for it was dropped. When creating an editor, a `Promise` is returned. Use `then/catch()` to define a callback when the editor is initialized or fails to start. The promise returns the created editor instance, e.g. `ClassicEditor`, on which you can listen to its events. Note: The editor instance is not the only object on which events are fired. You can also listen to e.g. `Document` events.
pasteFilter	N/A
pasteFromWordCleanupFile pasteFromWordPromptCleanup pasteFromWord_heuristicsEdgeList	N/A. The Paste from Word feature itself is planned.
plugins	See the `plugins` configuration option. The way how plugins are enabled in CKEditor 5 has changed in general. For more information check the articles about plugins and custom builds.
protectedSource	N/A
readOnly	See `editor.isReadOnly` and Read-only feature guide.
removeButtons	N/A. A similar effect can be achieved by setting the `toolbar` option with fewer buttons.
removeDialogTabs	N/A
removeFormatAttributes removeFormatTags	N/A
removePlugins	`removePlugins`
resize_dir resize_enabled resize_maxHeight resize_maxWidth resize_minHeight resize_minWidth	N/A
scayt_autoStartup scayt_contextCommands scayt_contextMenuItemsOrder scayt_customDictionaryIds scayt_customPunctuation scayt_customerId scayt_disableOptionsStorage scayt_elementsToIgnore scayt_handleCheckDirty scayt_handleUndoRedo scayt_ignoreAllCapsWords scayt_ignoreDomainNames scayt_ignoreWordsWithMixedCases scayt_ignoreWordsWithNumbers scayt_inlineModeImmediateMarkup scayt_maxSuggestions scayt_minWordLength scayt_moreSuggestions scayt_multiLanguageMode scayt_multiLanguageStyles scayt_sLang scayt_serviceHost scayt_servicePath scayt_servicePort scayt_serviceProtocol scayt_srcUrl scayt_uiTabs scayt_userDictionaryName	N/A. There is no spell checking plugin in CKEditor 5 at this moment. However, the native browser spell checker can be used in CKEditor 5.
sharedSpaces	N/A. CKEditor 5 Framework architecture allows for writing a custom editor that contains multiple editable elements (document roots). See the Document editor tutorial.
shiftEnterMode	N/A. `Shift` + `Enter` support is handled in https://github.com/ckeditor/ckeditor5-enter/issues/2
skin	In CKEditor 5 lots of changes to the interface can be easily made by changing the default CKEditor theme (see the Theme customization guide). For heavy UI modifications, like integrating CKEditor with a custom UI framework, building a custom editor is needed (see the Third-party UI guide).
smiley_columns smiley_descriptions smiley_images smiley_path	N/A
sourceAreaTabSize	N/A
specialChars	N/A
startupFocus	N/A
startupMode	N/A. View source feature is not planned, see https://github.com/ckeditor/ckeditor5/issues/592.
startupOutlineBlocks	N/A
startupShowBorders	N/A
stylesSet	N/A
stylesheetParser_skipSelectors stylesheetParser_validSelectors	N/A
tabIndex	N/A
tabSpaces	N/A
templates templates_files templates_replaceContent	N/A
title	N/A
toolbar	`toolbar` See also `contextualToolbar` to define the toolbar of a Balloon editor.
toolbarCanCollapse	N/A
toolbarGroupCycling toolbarGroups	N/A
toolbarLocation	N/A. Can be achieved by writing an editor with a customized UI view. See also the `DecoupledEditor` implementation.
toolbarStartupExpanded	N/A
uiColor	CKEditor 5 comes with a concept of much more powerful themes, where almost every aspect of the UI can be styled easily. See the Theme customization guide and Theme customization guide. Thanks to CSS variables rebuilding the editor is not needed to change its styles.
undoStackSize	`typing.undoStep`
uploadUrl	There are several image upload strategies supported by CKEditor 5. Check out the comprehensive "Image upload" guide to learn more.
useComputedState	N/A
width	Classic editor (CKEditor 5) no longer encapsulates the editing area in an `<iframe>`, which means that the height (and similar options) of the editing area can be easily controlled with CSS. For instance, to set the width of the Classic editor, use `.ck-editor { width:400px; }`. Setting the width of other editors which do not enclose the toolbar and the editable in a box (Inline editor, Balloon editor, etc.) can be achieved using `.ck-editor__editable_inline { width:400px; }`. See also How to set the height of CKEditor 5 (Classic editor).
wsc_cmd wsc_customDictionaryIds wsc_customLoaderScript wsc_customerId wsc_height wsc_lang wsc_left wsc_top wsc_userDictionaryName wsc_width	There is no spell checking plugin in CKEditor 5 at this moment. However, the native browser spell checker can be used in CKEditor 5.

If you are missing any particular features or settings, feel free to report an issue. Please be as precise as possible, explaining the exact use case, the context where the editor is used, and the expected behavior.