CKEditor Picture

Automatically converts CKEditor 5 inline images into responsive
elements with AVIF and WebP sources, and rewrites relative
URLs to absolute — built for headless and decoupled Drupal frontends.

When you build a decoupled Drupal site (React, Next.js, Astro, etc.), images inserted directly via CKEditor 5 are stored with
root-relative URLs (/sites/default/files/…) and plain <img> tags. These break on a frontend served from a
different domain, and they miss the performance benefits of modern formats like AVIF and WebP.

CKEditor Picture fixes this automatically at the text-processing layer: no editorial workflow changes required, no JavaScript, no
CDN dependency.

Features

• Converts CKEditor 5 direct file-upload <img> tags into <picture> elements with AVIF and WebP
  <source> alternatives.
• Rewrites root-relative src attributes to absolute URLs so decoupled frontends on any domain can load the image.
• Preserves <figure>, <figcaption>, alignment classes, alt, width,
  height, and loading attributes — nothing is lost.
• Graceful degradation: if a format is not supported by the image toolkit, that <source> is silently omitted and the
  browser falls back to the next one.
• Configurable image style names per text format via the standard Text formats admin UI.
• Automatically enables itself on all non-plain-text formats on install.
• Works transparently with JSON:API and REST — the transformation happens in body.processed, so no frontend code
  changes are needed.

Post-Installation

Run:

  drush en ckeditor_picture
  drush updb
  drush cr
  

That's it. The module adds itself to every HTML text format automatically. To verify or change settings, go to:

Administration → Configuration → Content authoring → Text formats

Select a format (e.g. Full HTML), find the "CKEditor inline images →
AVIF/WebP" filter, and configure the AVIF
and WebP image style machine names (defaults: body_avif and body_webp).

Both image styles are created on install. You can adjust their effects at:

Administration → Configuration → Media → Image styles

Additional Requirements

• Drupal 10.1 or 11
• CKEditor 5 (included in Drupal core)
• An image toolkit that supports AVIF and/or WebP:
  • GD: requires PHP compiled with --with-avif (PHP 8.1+) for AVIF; WebP support is standard in
    most PHP builds.
  • ImageMagick: requires libavif for AVIF; WebP is widely available.

If the toolkit does not support a format, that <source> is omitted and the browser uses the next available source.

Recommended modules/libraries

• ImageMagick: broader AVIF and WebP support than GD, and better
  performance for large images.
• Responsive Image (Drupal core): handles <picture> for Media Library embeds
  (<drupal-media> tags). CKEditor Picture complements it by covering direct file-upload <img> tags, which
  Responsive Image does not process.

Similar projects

• WebP: converts images sitewide via image styles but does not target CKEditor
  inline images or produce <picture> elements for decoupled consumers.
• Responsive Image (core): generates <picture> for Media Library embeds using responsive image
  styles, but only for <drupal-media> entities — not for images uploaded directly via CKEditor's file upload button.

CKEditor Picture is specifically designed for the direct-upload use case in decoupled architectures, where the
body.processed field is consumed by an external frontend.