Upgrading to CKEditor 5
Liferay 2025.Q2+ Beta Feature
Currently, this feature is behind a beta feature flag (LPD-11235).
CKEditor is Liferay’s WYSIWYG text editor used in various contexts, such as web content and rich text fields. CKEditor 5 is now a beta feature in Liferay DXP that revamps the editing experience and how these forms of content are rendered.
CKeditor 5 is the current, actively maintained version, and it will become the default text editor in a future release in 2026. CKEditor 4 is no longer maintained as of 2023, so you should plan to upgrade to avoid maintenance issues. You can enable the feature in a test environment to help plan for the upgrade and check old content for potential issues.
Upgrading from CKEditor 4 to CKEditor 5 has many advantages:
- It allows for a seamless copy-and-paste experience with other tools.
- It standardizes the editing experience across the rich text editors in Liferay DXP.
- The editing toolbar is always visible when content editors scroll down the page.
- And many more new features! See the CKEditor website for more feature highlights in CKEditor 5.
Upgrading to CKEditor 5 substantially enhances the editing experience for your site, although you should plan the upgrade carefully depending on your existing content.
Possible Upgrade Risks
Although some changes in CKEditor 5 upgrade automatically, the different way it renders HTML can affect existing content created with CKEditor 4. Back up your content created with CKEditor 4 before you attempt changes after the upgrade.
Enabling the LPD-11235 feature flag only enables CKEditor 5. Existing content contains HTML created with CKEditor 4, and isn’t changed. Content is only affected when it has older HTML from CKEditor 4 and you edit it with CKEditor 5.
Additionally, some features that you may have been using with CKEditor 4 may stop working when you publish it again with CKEditor 5:
- Some plugins are no longer supported with CKEditor 5. See the official chart for equivalent plugins in CKEditor 5. Newer plugins available with CKEditor 5 may be a better fit for your use case.
- Custom plugins created for CKEditor 4 require upgrading to be compatible with CKEditor 5, because the plugins API changed.
- Embedded videos, tables, or styles may break, because they are handled differently in CKEditor 5. See HTML Version Compatibility for details on which controls generate different HTML between the two versions.
- Styled text created before the upgrade may not respond to toolbar controls.
Most importantly, without manual intervention, keeping configurations or plugins from CKEditor 4 can cause data loss in old content when you publish it with CKEditor 5. Carefully check which of these cases apply to your content when you publish with CKEditor 5, and consider upgrading to newer, up-to-date plugins.
Performing the Upgrade
See CKEditor’s recommended migration strategy for the steps to upgrade. To load your content with CKEditor 5, edit it with the LPD-11235 beta feature flag enabled. To ensure the upgrade goes smoothly, try enabling the feature in a test environment to check your old content before you publish it.
Because the various style and page layout contexts in Liferay results in different HTML created with CKEditor, you should check all of your content created with CKEditor 4 manually for content that changes and must be fixed when you publish it with CKEditor 5. You can check your content at a pace that’s appropriate for your workflow, because the HTML is unaffected until it’s published again with the upgraded text editor.
As you check your old content, reference the official plugin chart and the HTML version compatibility table for help addressing specific issues.
HTML Version Compatibility
Although CKEditor versions 4 and 5 share many of the same controls in Liferay, some of them generate HTML differently after the upgrade. If the generated HTML changes, manual steps may be necessary to ensure the correct result.
Here are all of the controls used in Liferay’s CKEditor implementation (that create HTML), and whether the generated HTML is the same between these versions:
| Control | Same HTML in CKEditor 5? | Migration Notes |
|---|---|---|
Bold | Yes | |
BulletedList | Yes | |
HorizontalRule | Yes | |
ImageSelector | No; the CKEditor5 img element no longer contains the alt or data-fileentryid attributes | Despite the HTML difference, the result appears the same on the page, so no extra steps are needed. |
Italic | No; <em> tags in CKEditor 4 become <i> tags in CKEditor 5 | CKEditor 5 automatically converts <em> tags to <i> tags, so no extra steps are needed. |
JustifyCenter | Yes | |
JustifyLeft | Yes | |
JustifyRight | Yes | |
Link | Yes | |
NumberedList | Yes | |
Styles | No | The style CSS classes are different, and the control does not update when CKEditor 4 styles are selected. Manually replace the styles as needed. |
Table | No | CKEditor 5 attempts to convert raw table markup automatically, but the conversion is complicated. Manually verify or recreate tables if needed. |
Underline | Yes | |
VideoSelector | No | Embedded videos no longer work and may cause page rendering issues. CKEditor 5 relies on the Media embed plugin. |