Contribute to this guideReport an issue

guideMigration 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

Image upload is handled differently with CKEditor 5, bringing a much better user experience. Solutions used with CKEditor 4 may not be compatible anymore and therefore a new approach is needed.

CKEditor 5 Builds come with Easy Image available out of the box. It is super simple to enable image upload with it.

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

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-content { 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 Classic editor, call editor.ui.view.editable.editableElement.setAttribute('spellcheck', 'false'); after creating the editor.

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-content { 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 article.

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

Uploading images in CKEditor 5 is possible thanks to Easy Image powered by CKEditor Cloud Services which comes with support for responsive images. To configure it, provide the cloud services configuration. Uploading via CKFinder is available, too, see ckfinder.uploadUrl.

Writing your own image upload adapters is also possible, see https://stackoverflow.com/questions/46765197/how-to-enable-image-upload-support-in-ckeditor-5.

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 example, the width setting can be achieved with .ck-content { 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.