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 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.
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 {@link features/image-upload#easy-image Easy Image} available out of the box. It is super simple to {@link features/image-upload#easy-image enable image upload with it}.
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.
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/quick-start#creating-a-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 | 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 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 {@link examples/builds/balloon-editor Balloon} 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 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 Note: The {@link module:basic-styles/code~Code Code feature} is not available by default in any build, but can be enabled in a {@link builds/guides/development/custom-builds 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 |
| 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 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 {@link 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 {@link framework/guides/theme-customization 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 For Classic editor, call |
| 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 {@link builds/guides/development/custom-builds 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 {@link features/font 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 {@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 | 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 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_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 {@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 |
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 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 pasteFromWordPromptCleanup pasteFromWord_heuristicsEdgeList |
N/A. The Paste from Word feature itself is planned. |
| 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. For more information check the articles about {@link builds/guides/development/plugins plugins} and {@link builds/guides/development/custom-builds custom builds}. |
| protectedSource | N/A |
| readOnly | See {@link module:core/editor/editor~Editor#isReadOnly editor.isReadOnly} and {@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 |
N/A |
| removePlugins | {@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_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 {@link framework/guides/document-editor 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 {@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 |
| 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 |
{@link module:core/editor/editorconfig~EditorConfig#toolbar See also {@link module:core/editor/editorconfig~EditorConfig#balloonToolbar |
| 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 {@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 guide}. Thanks to {@link framework/guides/theme-customization#customization-with-css-variables CSS variables} rebuilding the editor is not needed to change its styles. |
| undoStackSize | {@link module:typing/typing~TypingConfig#undoStep typing.undoStep} |
| uploadUrl |
Uploading images in CKEditor 5 is possible thanks to {@link features/image-upload#easy-image Easy Image} powered by CKEditor Cloud Services which comes with support for responsive images. To configure it, provide the {@link module:cloud-services/cloudservices~CloudServicesConfig cloud services configuration}. Uploading via CKFinder is available, too, see {@link module:adapter-ckfinder/uploadadapter~CKFinderAdapterConfig#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 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 {@link builds/guides/support/reporting-issues#reporting-issues-2 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.