Contribute to this guide

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

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.

Note that only content that is explicitly converted between the model and the view by the editor plugins will be preserved in CKEditor 5. Check the conversion tutorials to learn how to extend the conversion rules.

autoEmbed_widget Refer to the Media embed feature guide to learn more about media embedding in CKEditor 5.
autoGrow_bottomSpace
autoGrow_maxHeight
autoGrow_minHeight
autoGrow_onStartup

These settings are no longer needed as by default, CKEditor 5 automatically grows with content.

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-editor__editable_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.
autocomplete_commitKeystrokes N/A
autolink_commitKeystrokes
autolink_emailRegex
autolink_urlRegex
N/A
baseFloatZIndex N/A. There is a dedicated issue about z-index management and making it more open for developers.
baseHref Not supported yet, see the relevant GitHub issue.
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, balloon block, inline or decoupled editor you may add a class to the element on which the editor is initialized.

Additionally, all editor types use .ck-content on their main root editable elements. This class can thus also be used to write stylesheet rules for the editor content.

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, balloon block, inline or decoupled editor you may add a class to the element on which the editor is initialized.

Additionally, all editor types use .ck-content

on their main root editable elements. This class can thus also be used to write stylesheet rules for the editor content.

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
cloudServices_tokenUrl See config.cloudServices.tokenUrl.
cloudServices_uploadUrl See config.cloudServices.uploadUrl. Check out the comprehensive "Image upload" guide to learn more.
codeSnippetGeshi_url
codeSnippet_codeClass
codeSnippet_languages
codeSnippet_theme

Code blocks are not supported yet, but are coming soon.

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 (see the Basic styles feature guide).

colorButton_backStyle
colorButton_colors
colorButton_colorsPerRow
colorButton_enableAutomatic
colorButton_enableMore
colorButton_foreStyle
colorButton_normalizeBackground

Refer to the Font feature guide to learn more about configuring font and background color in CKEditor 5.

At the same time, we also 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 Refer to the Setting the language of the content guide to learn how to set the content direction using the config.language configuration option.
contentsLanguage Refer to the Setting the language of the content guide to learn how to set the content language using the config.language configuration option.
contextmenu_contentsCss No longer needed as CKEditor 5 does not have its own context menu.
copyFormatting_allowRules
copyFormatting_allowedContexts
copyFormatting_disallowRules
copyFormatting_keystrokeCopy
copyFormatting_keystrokePaste
copyFormatting_outerCursor
The copy formatting feature is not available yet.
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

CKEditor 5 uses the <sub> element.

Note: The Subscript feature is not available by default in any build, but can be enabled in a custom build (see the Basic styles feature guide).

coreStyles_superscript

CKEditor 5 uses the <sup> element.

Note: The Superscript feature is not available by default in any build, but can be enabled in a custom build (see the Basic styles feature guide).

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 the UI language feature guide.
devtools_styles
devtools_textCallback
The old CKEditor 4 Developer Tools plugin is not available for CKEditor 5. However, check out the new CKEditor 5 inspector which is a far more advanced tool that will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
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

Note: An official integration of the spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, WProofreader.

A dedicated configuration option to disable the native browser spell checker is unavailable. However, in case of inline, balloon and balloon block editors it can be done by setting the spellcheck attribute directly on the element where CKEditor should be enabled.

Additionally, for all types of editors, including the classic and decoupled ones, you can also 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 See config.allowedContent. No longer needed as CKEditor 5 removes all unwanted markup that cannot be edited with the editor.
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.
easyimage_class
easyimage_defaultStyle
easyimage_styles
easyimage_toolbar
Refer to the Easy Image and Images feature guides to learn more about image-related features and Easy Image integration in CKEditor 5.
emailProtection N/A
embed_provider Refer to the Media embed feature guide to learn more about media embedding in CKEditor 5.
emoji_emojiListUrl
emoji_minChars
Emoji can be pasted into CKEditor 5 as Unicode content. You can use the emoji picker of your operating system to insert emoji characters. Use the Ctrl+Cmd+Space keyboard shortcut on macOS, Win+. on Windows or the relevant emoji key on the touch keyboard of your device to open the picker.
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 can be used for creating soft line breaks.

entities
entities_additional
entities_greek
entities_latin
entities_processNumerical
N/A
extraAllowedContent See config.allowedContent.
extraPlugins Learn how to install plugins in CKEditor 5.
fileTools_defaultFileName
fileTools_requestHeaders
N/A
filebrowserBrowseUrl
filebrowserFlashBrowseUrl
filebrowserFlashUploadUrl
filebrowserImageBrowseLinkUrl
filebrowserImageBrowseUrl

filebrowserUploadMethod
filebrowserUploadUrl
filebrowserWindowFeatures
filebrowserWindowHeight
filebrowserWindowWidth
There is no equivalent of the file browser plugin in CKEditor 5 yet. See also config.uploadUrl.
fillEmptyBlocks Blocks are always filled in CKEditor 5 because this ensures that the intention of the content author (who left such empty lines) will be preserved in the output data.
find_highlight The find and replace feature is not available yet.
flashAddEmbedTag
flashConvertOnEdit
flashEmbedTagOnly
N/A
floatSpaceDockedOffsetX
floatSpaceDockedOffsetY
floatSpacePinnedOffsetX
floatSpacePinnedOffsetY
floatSpacePreferRight
N/A
fontSize_defaultLabel
fontSize_sizes
fontSize_style
font_defaultLabel
font_names
font_style
Refer to the Font feature guide to learn more about font size, family and color support in CKEditor 5.
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 enabled editor plugins.
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 config.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 An official integration of the spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, WProofreader.
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-editor__editable_inline { height:400px; }.

In order to set the height dynamically (from JavaScript) use the view writer:

editor.editing.view.change( writer => {
    writer.setStyle( 'height', '400px', editor.editing.view.document.getRoot() );
} );

See also How to set the height of CKEditor 5 (Classic editor).

htmlEncodeOutput N/A. CKEditor 5 outputs HTML markup. See also this StackOverflow question and a dedicated issue.
ignoreEmptyParagraph N/A
image2_alignClasses Available via more powerful config.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_maxSize
image2_prefillDimensions
Refer to the Images feature guide to learn more about image-related features and customization options in CKEditor 5.
imageUploadUrl See config.uploadUrl.
image_prefillDimensions
image_previewText
image_removeLinkByEmptyURL
Refer to the Images feature guide to learn more about image-related features and customization options in CKEditor 5.
indentClasses
indentOffset
indentUnit
Refer to the Configuring the block indentation feature guide to learn how to customize the indentation behavior using offsets, units or classes.
jqueryOverrideVal N/A
justifyClasses Refer to the 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
The support for multiple translations is handled by the translations service. See the UI language feature guide.
linkDefaultProtocol N/A
linkJavaScriptLinksAllowed N/A
linkPhoneMsg
linkPhoneRegExp
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. Math equation functionality for CKEditor 5 is provided by a partner solution, MathType.
mentions Refer to the Mentions feature guide to learn more about smart autocompletion based on user input in CKEditor 5.
menu_groups
menu_subMenuDelay
CKEditor 5 does not come with a context menu. Contextual, configurable inline toolbar is preferred instead to offer contextual actions for features such as table or image. See also toolbar.
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 Not needed as CKEditor 5 always trims the pasted content to match what the available plugins can handle. If you would like to filter the pasted content even further, please report a ticket.
pasteFromWordCleanupFile
pasteFromWordNumberedHeadingToList
pasteFromWordPromptCleanup
pasteFromWordRemoveStyles
pasteFromWord_heuristicsEdgeList
pasteFromWord_inlineImages
Refer to the Paste from Word feature guide to learn more about support for pasting from Microsoft Word in CKEditor 5.
pasteTools_keepZeroMargins Refer to the Paste from Word and Paste from Google Docs feature guides to learn more about support for pasting from external applications in CKEditor 5.
plugins See the plugins configuration option. The way how plugins are enabled in CKEditor 5 has changed in general. Check the articles about plugins and custom builds for more information.
protectedSource N/A
readOnly See editor.isReadOnly and refer to the 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
Refer to the Removing text formatting feature guide to learn how to quickly remove any text formatting applied using inline HTML elements and CSS styles in CKEditor 5.
removePlugins See config.removePlugins.
resize_dir
resize_enabled
resize_maxHeight
resize_maxWidth
resize_minHeight
resize_minWidth
No longer needed. The editor automatically grows with content. You can also limit its height with min-height and max-height or set it with height if you need. If you want to allow the users to manually resize the editor, you need to implement this by behavior by yourself.
scayt_autoStartup
scayt_cacheSize
scayt_contextCommands
scayt_contextMenuItemsOrder
scayt_customDictionaryIds
scayt_customPunctuation
scayt_customerId
scayt_disableCache
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
The spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, WProofreader.
sharedSpaces

N/A.

The decoupled editor allows configuring where should the toolbar and the editable element be inserted.

In addition to that, CKEditor 5 Framework architecture allows for writing a custom editor that contains multiple editable elements (document roots). See the multi-root editor example.

shiftEnterMode

N/A. CKEditor 5 always creates a new paragraph (<p> element) as specified by Editor Recommendations - Enter key.

Shift+Enter can be used for creating soft line breaks.

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. There is no smiley plugin in CKEditor 5. However, emoji can be pasted into the rich-text editor as Unicode content.
sourceAreaTabSize N/A
specialChars N/A. There is no special characters plugin in CKEditor 5 yet.
startupFocus N/A
startupMode N/A. View source feature is not planned, see the relevant GitHub issue.
startupOutlineBlocks N/A
startupShowBorders N/A
stylesSet Not available yet. Refer to the relevant GitHub issue.
stylesheetParser_skipSelectors
stylesheetParser_validSelectors
N/A
tabIndex N/A
tabSpaces N/A
templates
templates_files
templates_replaceContent
N/A
title N/A
toolbar

See config.toolbar.

See also config.balloonToolbar to define the toolbar of a balloon editor and the block toolbar feature.

toolbarCanCollapse N/A. The toolbar cannot be collapsed manually by the user. For distraction-free editing with the toolbar appearing when you need it, use inline, balloon or balloon block editor.
toolbarGroupCycling
toolbarGroups
N/A. Toolbar buttons can be grouped by using '|' as a separator.
toolbarLocation N/A. Can be achieved by using the decoupled editor or writing an editor with a customized UI view.
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 example. Thanks to CSS variables rebuilding the editor is not needed to change its styles.
undoStackSize See config.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 any of the editor types, use .ck-editor__editable_inline { width:400px; }.

In order to set the width dynamically (from JavaScript) use the view writer:

editor.editing.view.change( writer => {
    writer.setStyle( 'width', '400px', editor.editing.view.document.getRoot() );
} );

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
The spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, WProofreader.

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