rte_ckeditor_image for TYPO3: Image Editing in the Rich Text Editor

rte_ckeditor_image brings professional image management into the rich text editor

The TYPO3 CKEditor only allows simple image embeds via an img tag, without any connection to the file abstraction layer and without responsive variants. For editorial teams that regularly place images inside articles, news posts or magazine texts, that is not enough: they need scaling, alt text, captions, link target and, above all, sharp output on high-density displays. rte_ckeditor_image from Netresearch adds exactly these functions to the CKEditor and integrates them cleanly with the FAL. On every TYPO3 project with editor-maintained inline images, the extension has been the standard tool for years and counts as one of the most frequently installed editorial helpers in the ecosystem.

Typical use cases live in editorial teams with high image volume

Online magazines and corporate news sites are the classic audience. A magazine with 200 articles per year embeds two to five images per article in running text, on top of teaser and header images. Without rte_ckeditor_image, the editors would have to accept a content element switch for every inline image and break the flow of writing. With the extension, they insert the image directly through a toolbar button, pick the FAL reference, set alt text and caption and return to writing without any context switch. The efficiency gain is measurable in practice: on an editorial team with 200 articles per year and an average of four images per article, we save around two minutes of setup time per article, which adds up to roughly 30 working hours per year.

A second scenario are product catalogues and technical documentation. Anyone who maintains step-by-step instructions with inline screenshots in a TYPO3 catalogue needs the images directly in the text. rte_ckeditor_image allows this with the same FAL references that are used in the rest of the project, so image updates happen in one place and propagate everywhere.

A third scenario is the migration of TYPO3 installations from the htmlArea era. Anyone who was using RTEhtmlArea before found a similar image management there. When switching to CKEditor, rte_ckeditor_image is the direct replacement extension, so that editors can keep their familiar workflow. Without the extension, they lose not only a function on upgrade but an entire work step that can only be clumsily rebuilt through additional content elements.

Technical architecture extends the CKEditor toolbar via plug-in

The extension consists of a CKEditor plug-in that registers the image button and the image dialog, plus a server-side rendering that translates the marker in the stored HTML into a Fluid output. The plug-in talks to an AJAX endpoint that processes the FAL reference, the image dimensions and the alt texts.

In the database content, the image is stored as an HTML marker with the data attributes data-htmlarea-file-uid and data-htmlarea-file-table, accompanied by further attributes for zoom, quality level, width and height. On rendering, a preUserFunc in lib.parseFunc_RTE processes the marker tag: it scales the image through TYPO3 image processing, sets the lazy loading attribute and outputs figure, link and caption through overridable Fluid partials. The upper limits for width and height are set in Page TSconfig (maxWidth, maxHeight). A typical magazine setup works with three to five image widths (480, 768, 1024, 1440, 2048) and needs a custom preUserFunc for the srcset, as shown by example in the extension documentation; the extension itself generates no srcset.

The image dialog sets width, height, alt text, title, quality level and click-to-enlarge. Cropping with crop variants is only offered by the regular image content element. Width and height are stored per image instance, so that the same FAL image can appear at different sizes in different articles. This matters especially when an image is used at different sizes in both the magazine teaser and the running text, without the editorial team having to maintain two separate files.

Common problems involve responsive output, WebP and CKEditor 5 compatibility

The most common support topic is missing srcset output. The default rendering path never produces a srcset, only a scaled image version. There is no setting for srcset widths, neither in the RTE YAML nor in the extension configuration. The solution is a custom preUserFunc following the documentation example, which generates a processed variant for each width.

The second problem is WebP. Anyone who wants to deliver modern image formats has to set up the TYPO3 ImageMagick provider or a GraphicsMagick setup with WebP support. rte_ckeditor_image itself does not handle WebP conversion but delegates to the core image processor. Without correct provider configuration, the images stay as JPEG in the output.

Thirdly, CKEditor 5 represents an architectural change. TYPO3 v12 ships CKEditor 5, which uses a different plug-in model. rte_ckeditor_image versions 12.x for TYPO3 v12 and 13.x for v13 and v14 are ported to CKEditor 5 and work out of the box. Custom adjustments based on CKEditor 4 have to be adapted on upgrade. Anyone who has built custom plug-ins or their own toolbar buttons should plan at least one or two developer days for the migration.

Migration to TYPO3 v12 and v13 requires a version jump of the extension

rte_ckeditor_image is actively maintained by Netresearch and is available for TYPO3 v11, v12 and v13. The bigger jump lies between the extension series 11.x with CKEditor 4 and the series 12.x and 13.x with CKEditor 5. Anyone lifting a TYPO3 v10 or v11 installation with extension 10.x or 11.x to TYPO3 v12 has to switch to the 12.x series of the extension at the same time. The database representation of inline images remains compatible, so existing articles work without content migration.

At Gosign, we check before every TYPO3 upgrade whether the project RTE YAML has to be adapted to the extension version and whether custom plug-in adjustments or overridden ViewHelpers exist. On many projects with TYPO3 v12, it is also worth checking whether images as separate content elements are sufficient and whether the extension can be phased out in the medium term. For editorial teams that need images inside running text, however, rte_ckeditor_image remains the most pragmatic option. The alternative would be a custom image toolbar button with its own CKEditor plug-in, which is significantly more effort and permanently shifts maintenance into the project responsibility.