ckeditor5 48.2.0

v48.2.0

on Node.js Yarn

We are happy to announce the release of CKEditor 5 v48.2.0.

Release highlights

Media embed improvements

The Media embed feature now supports resizing with drag handles and styling, including alignment with optional text wrapping. Embedded videos and other media can be aligned left, right, or centered, with surrounding content flowing around them.

Editor roots on paragraph-like elements

Editor roots can now be attached to or created as block-level elements other than the default container, including headings, paragraphs, and custom block elements with their own classes, styles, and attributes. This helps integrate CKEditor 5 with CMSes and other systems that edit individual content fields rather than a single wrapper.

Skip-level lists

The list feature now supports skip-level lists. List items can be nested at non-sequential indentation levels, for example a third-level item placed directly under a first-level one, preserving the structure of documents imported or pasted from Word and HTML sources.

General HTML Support in CKEditor AI

CKEditor AI now works in editors configured with General HTML Support. AI Chat, AI Quick Actions, and AI Review can apply and suggest changes on content that uses additional elements and attributes.

Paste and drag and drop in AI Chat

The AI Chat input now supports pasting and drag and drop. Screenshots from the clipboard and other images are added as context attachments, URLs are detected and displayed as link pills, and long pasted text is attached as a text file.

Other AI improvements

• Multi-root and multi-editor support. AI Chat and AI Review now support multi-root and multi-editor integrations, including adding or removing editor instances at runtime.
• Default typography improvements for AI Chat responses. AI Chat now includes built-in styles for common content types, improving the readability of generated output.
• Resilient streaming. Streaming replies in AI Chat are no longer cancelled when the page is closed or reloaded. The reply keeps streaming on the server and reconnects when the conversation is reopened.

MINOR BREAKING CHANGES ℹ️

• ai: Changed CKEditor AI APIs used by custom workflows. Review the following changes and see the API documentation for details.

  • Removed methods:

    • AIChatContext#updateCurrentDocument() (use AIChatContext#updateCurrentDocuments() instead).
    • AIEditing#sessionId (use AIEditing#getSessionId( editor ) instead).
    • AIChatContext#getSourceByDataId()
    • AIChatContext#getDocumentContextSliceByDataId()

  • Removed properties:

    • AIReply#documentId
    • AIReply#newNodeAnchorIds
    • AIReply#dataIdDocumentSources

  • Modified method signature:

    • AIReply#appendContent( content )
    • AIEditing#modelToDataWithIds( modelFragment )
    • AIChatController#addSelectionToChatContext()
    • AIEditing#getSelectionText()

  • Modified property type:

    • AIReply#content
    • AIReply#parsedContent
    • AIReply#parsedMergedContent
    • AIReply#documentContextContent

Features

• core, editor-balloon, editor-classic, editor-decoupled, editor-inline, editor-multi-root, ui: Added support for describing editable root elements through config.root.element and config.roots.<rootName>.element without supplying an existing DOM node. The configuration now accepts a tag-name string, such as 'h1', or a ViewRootElementDefinition object that defines the tag name, CSS classes, inline styles, and attributes. The <textarea> and <input> elements are not supported because they cannot host rich-text editables. Closes #20047.

• collaboration-core, track-changes: Track Changes now integrates with the General HTML Support feature. GHS-produced elements and attributes are now tracked as suggestions instead of being applied silently to the document content.

  Changing GHS-produced HTML attributes, classes, or inline styles creates attribute suggestions. Suggestion descriptions now list inline styles by name and value, such as Set format: border-color (green), and group class or HTML-attribute changes under concise labels, such as Set format: style, metadata. Insertion and deletion suggestions for GHS-driven elements, such as <section>, <iframe>, and <article>, now use HTML element names.

• collaboration-core, track-changes: Track Changes now records suggestions for media embed resize and style changes.

• autoformat, list: Numbered list autoformat now accepts any starting number. Typing any number followed by . or ) and a space (e.g. 5. ) creates a numbered list. When the list.properties.startIndex option is enabled, the list starts at the typed number.

• ai: Introduced General HTML Support integration with CKEditor 5 AI. AI Chat, AI Quick Actions, and AI Review can now process content that uses additional HTML elements and attributes.

• ai: Introduced a programmatic API for the AIReview plugin. See details in the Using CKEditor AI programmatically documentation.

• ai: Introduced paste support in the AI Chat input.

  Pasting a single bare URL adds it to the conversation context as a link pill. Pasting plain text above a configurable threshold attaches it as a .txt file. Pasting an image or any supported file attaches it to the conversation context as a file pill, with image pills using a dedicated icon.

• ai: Introduced drag-and-drop support to the AI Chat input.

  Files dropped onto the prompt input area are added to the chat context as pills. URLs and text dropped from the browser are also added to the conversation context as corresponding pills. The AI Chat input panel now shows a visual hint during the drag.

• editor-multi-root: The MultiRootEditor#createEditable() method now accepts an existing HTMLElement or a ViewRootElementDefinition, so dynamically added roots can be attached to caller-owned DOM elements. Element definitions supplied at root configuration time are also replicated through real-time collaboration. Closes #20047.

• email: Tables with resized columns now keep their column widths when exported as email. Previously, they fell back to auto-distributed sizing in Outlook and other email clients.

• list: Added support for skip-level lists. List items can now be indented by more than one level at a time by enabling the list.enableSkipLevelLists configuration option. Closes #12563.

• media-embed: Introduced the media embed resize feature that allows users to resize embedded media via drag handles. Closes #6593.

  Embedded media now uses the aspect-ratio CSS property instead of a padding-bottom wrapper.

• media-embed: Introduced the media embed alignment feature, with optional text wrapping. Closes #2781.

• media-embed: Added config.mediaEmbed.styles.options for picking a subset of the built-in media embed styles, overriding their fields, or registering custom ones. The config.mediaEmbed.toolbar now also accepts inline split-button dropdown definitions. Closes #20131.

Bug fixes

• clipboard, paste-from-office: Fixed ClipboardPipeline and PasteFromOffice to allow common HTML string normalization before conversion to the view. Closes #17309.

• ai: Fixed an issue where AI Chat temporarily displayed wrap and unwrap proposed changes as removals before converting them to formatting changes.

• ai: The editor no longer crashes when users interact with double-unwrap proposed changes, such as changes in nested block quotes or custom widgets.

• ai: AI Chat Shortcuts buttons are now disabled while a context item is being uploaded, preventing the shortcut from executing until the context is ready.

• ai: Fixed the model-nodelist-offset-out-of-bounds error thrown by AI Quick Actions when the selection started at the end of the previous block, for example when selecting a full paragraph that begins after the trailing boundary of the block above it.

• ai: The preview balloon now scrolls back to the top when switching between AI Chat suggestions.

• ai: AI plugins no longer block editor initialization with HTTP requests. Model fetching, conversation creation, and review checks loading now run in the background while the editor becomes interactive immediately.

• ai: Fixed a visible scrollbar appearing in AI suggestion boxes caused by suggestion marker borders being clipped by the container overflow.

• ai: Improved AI Chat stability in multi-editor setups.

  AI Chat no longer crashes when users interact with suggestions or replies from destroyed editors or removed roots. The "Current document" chat context option now reflects the presence of editor instances, and Track Changes suggestion actions now behave consistently across multiple editors.

• ai: Fixed an issue where the HTML Embed widget could be duplicated after content was processed by AI features.

• ai: The AI Review "review completed" header title now truncates with an ellipsis when it overflows the available space in the check results view, matching the behavior of the empty-results completed view.

• ai: Preserved whitespace and newlines inside preformatted blocks in AI Chat replies.

• document-outline: Fixed headingId attribute handling for custom heading elements configured with non-standard model names, such as heading2, or object-based view definitions, such as view: { name: 'h2', classes: 'fancy' }. Previously, such configurations could result in errors during editor.data.parse(...) processing.

• footnotes: Fixed incorrect spacing of the footnotes list divider.

• heading: The Title feature now handles editor configurations where some or all roots use a custom modelElement. Roots that do not accept the title element are skipped at runtime, and the feature logs a single warning when no root supports the title structure. Closes #20026.

• html-support: The General HTML Support schema for the hgroup element now works in editor configurations using a custom root modelElement. Closes #20026.

• html-support: The HTML comments feature no longer assumes the root model element is $root. Comments are now preserved in editor configurations using a custom root modelElement. Closes #20026.

• link: The link preview button now displays the no URL label for links with an empty href. Closes #20136.

• link: Fixed an issue where the link edit form back button was hidden when editing a link with an empty URL via the balloon toolbar. See #20136.

• link: Fixed text centering in the link preview button. See #20136.

• media-embed: Spotify track embeds now use a fixed height instead of a fluid aspect ratio to prevent incorrect resizing.

  Spotify track embeds now render at a fixed 80px height, matching the compact single-row player. Album and artist embeds are unaffected and continue to use a responsive aspect ratio.

• pagination: The pagination page navigator no longer changes its width based on the document's page count, so the toolbar's "show more items" button stays visible when long documents are loaded.

• paste-from-office: Fixed an issue where list items pasted from Word with three or more nesting levels could appear too far to the right when ancestor items had explicit paragraph indentation. Their position now matches Word's visual layout regardless of nesting depth.

• paste-from-office: Lists pasted from Microsoft Word now keep consistent left indentation. Closes #20179.

  Top-level list items that shared the same indentation in the original document no longer become visually misaligned in the editor when the list is interrupted by another list or by an empty paragraph. Nested list items pasted directly after their parent now keep their nesting level.

Other changes

• ai: AI Chat messages now use larger body text, a clearer heading hierarchy, more spacing between list items, and distinct styling for code, tables, block quotations, and horizontal rules.
• ai: Streaming replies in AI Chat are no longer cancelled when the page is closed or reloaded. The reply keeps streaming on the server, and returning to the conversation reconnects to it and displays the remaining content. The reply is cancelled only when the Stop generating button is used.
• image: Inline images are no longer allowed in roots or other limit elements that do not accept block content, such as $inlineRoot and custom inline-only roots. This also applies to custom limit element types contributed by integrators. Closes #20047.
• ui: The HighlightedTextView component now processes text containing HTML-special characters, such as &, <, and >.

Released packages

Check out the Versioning policy guide for more information.