category: builds-guides
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 {@link builds/guides/overview#when-not-to-use-builds When NOT to use CKEditor 5 Builds?} for more information.
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 {@link builds/guides/integration/installation Installation} for more details.
The API for integrating CKEditor with your pages also changed. It is worth checking {@link builds/guides/integration/basic-api Basic API} for an introduction.
When it comes to {@link features/index features}, there are two aspects that need to be taken into consideration:
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.
CKEditor 5 supports several different image upload strategies. Check out the {@link features/image-upload comprehensive "Image upload" guide} to find out the best option for your project.
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 {@link builds/guides/development/plugins#creating-plugins Creating plugins} section for more information on the development of plugins.
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, {@link framework/guides/theme-customization custom theming} in CKEditor 5 is much more powerful and simpler than before.
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.
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 {@link framework/guides/creating-simple-plugin Creating a simple plugin} article. Looking at the source code of CKEditor 5 plugins may also give you a lot of inspiration. |
| autoEmbed_widget | Refer to the {@link features/media-embed Media embed feature} guide to learn more about media embedding in CKEditor 5. |
| autoGrow_bottomSpace autoGrow_maxHeight autoGrow_minHeight autoGrow_onStartup |
Classic editor (CKEditor 5) no longer encapsulates the editing area in an 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 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 {@link examples/builds/balloon-editor balloon}, {@link examples/builds/balloon-block-editor balloon block}, or {@link examples/builds/inline-editor 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, balloon block 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 |
| cloudServices_tokenUrl | See {@link module:cloud-services/cloudservices~CloudServicesConfig#tokenUrl `cloudServices.tokenUrl`}. |
| cloudServices_uploadUrl | See {@link module:cloud-services/cloudservices~CloudServicesConfig#uploadUrl `cloudServices.uploadUrl`}. Check out the {@link features/image-upload 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 |
| colorButton_backStyle colorButton_colors colorButton_colorsPerRow colorButton_enableAutomatic colorButton_enableMore colorButton_foreStyle colorButton_normalizeBackground |
Refer to the {@link features/font#configuring-the-font-color-and-font-background-color-features 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 |
| 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 {@link features/ui-language#setting-the-language-of-the-content Setting the language of the content} guide to learn how to set the content direction using the {@link module:core/editor/editorconfig~EditorConfig#language `config.language`} configuration option. |
| contentsLanguage | Refer to the {@link features/ui-language#setting-the-language-of-the-content Setting the language of the content} guide to learn how to set the content language using the {@link module:core/editor/editorconfig~EditorConfig#language `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 Note: The {@link module:basic-styles/subscript~Subscript Subscript feature} is not available by default in any build, but can be enabled in a {@link builds/guides/development/custom-builds custom build} (see the {@link features/basic-styles Basic styles} feature guide). |
| coreStyles_superscript |
CKEditor 5 uses the Note: The {@link module:basic-styles/superscript~Superscript Superscript feature} is not available by default in any build, but can be enabled in a {@link builds/guides/development/custom-builds custom build} (see the {@link features/basic-styles Basic styles} feature guide). |
| coreStyles_underline |
CKEditor 5 uses the Note: The {@link module:basic-styles/underline~Underline Underline feature} is not available by default in any build, but can be enabled in a {@link builds/guides/development/custom-builds custom build} (see the {@link features/basic-styles 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 {@link features/ui-language 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 {@link framework/guides/development-tools#ckeditor-5-inspector 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 {@link framework/guides/theme-customization 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, {@link features/spelling-and-grammar-checking 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 For the classic and decoupled editors, call:
|
| 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 {@link features/easy-image Easy Image} and {@link features/image 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 {@link features/media-embed 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 ( 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 | Enabling extra plugins is possible by creating a {@link builds/guides/development/custom-builds custom build}. |
| 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 | 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 |
Refer to the {@link features/font 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 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 {@link module:heading/heading~HeadingConfig#options heading.options}. See also the {@link features/headings 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, {@link features/spelling-and-grammar-checking WProofreader}. |
| height |
Classic editor (CKEditor 5) no longer encapsulates the editing area in an 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 {@link module:image/image~ImageConfig#styles 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 {@link features/image 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 {@link features/image Images feature} guide to learn more about image-related features and customization options in CKEditor 5. |
| indentClasses indentOffset indentUnit |
Refer to the {@link features/indent#configuring-the-block-indentation-feature 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 {@link features/text-alignment Text alignment feature} guide. |
| keystrokes |
Keystroke handlers can be registered using {@link module:core/editingkeystrokehandler~EditingKeystrokeHandler Making keystrokes overridable through |
| language language_list |
The support for multiple translations is handled by the translations service. See the {@link features/ui-language 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](https://github.com/ckeditor/ckeditor5/issues/407). |
| mathJaxClass mathJaxLib |
N/A. Math equation functionality for CKEditor 5 is provided by a partner solution, {@link features/math-equations MathType}. |
| mentions | Refer to the {@link features/mentions 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 inline toolbar is preferred instead to offer contextual actions. |
| 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 Note: The editor instance is not the only object on which events are fired. You can also listen to e.g. {@link module:engine/model/document~Document `Document`} events. |
| pasteFilter | N/A |
| pasteFromWordCleanupFile pasteFromWordNumberedHeadingToList pasteFromWordPromptCleanup pasteFromWordRemoveStyles pasteFromWord_heuristicsEdgeList pasteFromWord_inlineImages |
Refer to the {@link features/paste-from-word Paste from Word feature} guide to learn more about support for pasting from Microsoft Word in CKEditor 5. |
| pasteTools_keepZeroMargins | Refer to the {@link features/paste-from-word Paste from Word} and {@link features/paste-from-word Paste from Google Docs} feature guides to learn more about support for pasting from external applications in CKEditor 5. |
| plugins | See the {@link module:core/editor/editorconfig~EditorConfig#plugins plugins} configuration option. The way how plugins are enabled in CKEditor 5 has changed in general. Check the articles about {@link builds/guides/development/plugins plugins} and {@link builds/guides/development/custom-builds custom builds} for more information. |
| protectedSource | N/A |
| readOnly | See {@link module:core/editor/editor~Editor#isReadOnly editor.isReadOnly} and refer to the {@link features/read-only Read-only feature} guide. |
| removeButtons | N/A. A similar effect can be achieved by setting the {@link module:core/editor/editorconfig~EditorConfig#toolbar toolbar} option with fewer buttons. |
| removeDialogTabs | N/A |
| removeFormatAttributes removeFormatTags |
Refer to the {@link features/remove-format 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 {@link module:core/editor/editorconfig~EditorConfig#removePlugins removePlugins}. |
| resize_dir resize_enabled resize_maxHeight resize_maxWidth resize_minHeight resize_minWidth |
N/A |
| 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, {@link features/spelling-and-grammar-checking WProofreader}. |
| sharedSpaces | N/A. CKEditor 5 Framework architecture allows for writing a custom editor that contains multiple editable elements (document roots). See the {@link framework/guides/document-editor Document editor tutorial}. |
| shiftEnterMode |
N/A. CKEditor 5 always creates a new paragraph ( 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 {@link examples/theme-customization Theme customization guide}. For heavy UI modifications, like integrating CKEditor with a custom UI framework, building a custom editor is needed. See the {@link examples/theme-customization 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](https://github.com/ckeditor/ckeditor5/issues/1110). |
| 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 |
See {@link module:core/editor/editorconfig~EditorConfig#toolbar See also {@link module:core/editor/editorconfig~EditorConfig#balloonToolbar |
| 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 {@link examples/builds/inline-editor inline}, {@link examples/builds/balloon-editor balloon} or {@link examples/builds/balloon-block-editor balloon block} editor. |
| toolbarGroupCycling toolbarGroups |
N/A. {@link module:core/editor/editorconfig~EditorConfig#toolbar Toolbar buttons can be grouped} by using `'|'` as a separator. |
| toolbarLocation | N/A. Can be achieved by writing an editor with a customized UI view. See also the {@link module:editor-decoupled/decouplededitor~DecoupledEditor 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 {@link framework/guides/theme-customization Theme customization guide} and {@link examples/theme-customization Theme customization example}. Thanks to {@link framework/guides/theme-customization#customization-with-css-variables CSS variables} rebuilding the editor is not needed to change its styles. |
| undoStackSize | See {@link module:typing/typing~TypingConfig#undoStep typing.undoStep}. |
| uploadUrl |
There are several image upload strategies supported by CKEditor 5. Check out the {@link features/image-upload comprehensive "Image upload" guide} to learn more. |
| useComputedState | N/A |
| width |
Classic editor (CKEditor 5) no longer encapsulates the editing area in an 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, {@link features/spelling-and-grammar-checking WProofreader}. |
If you are missing any particular features or settings, feel free to {@link builds/guides/support/reporting-issues#reporting-issues-2 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.