CKEditor Ecosystem Documentation
Search
Contribute to this guide
Home/CKEditor 5/Features

Image upload overview

Inserting images into content created with CKEditor 5 is quite a common task. In a properly configured rich-text editor, there are several ways for the end user to insert images:

  • Pasting an image from the clipboard.
  • Dragging a file from the file system.
  • Selecting an image through the file system dialog.
  • Selecting an image from the media management tool in your application.
  • Pasting a URL to an image, either into the editor dialog or directly into the content.

# Demo

This demo is configured to use CKBox for image upload and management. Use the image upload button Image to upload images or the CKBox button Open file manager to browse and select existing images from the file manager. It also includes the AutoImage plugin, which lets you paste image URLs directly.

Uploading images

To upload an image, do the following:

  1. Use the file insert toolbar button to open the upload dialog.
  2. Select an image and confirm upload.

The image will appear in the content.

Inserting images from CKBox

To insert an image using CKBox, do the following:

  1. Use the file manager toolbar button to open the CKBox dialog.
  2. Select an image and click the Choose button.

The image will appear in the content.

Note: You can choose more than one file at a time. You can also upload images while inside CKBox with its native upload mechanism.

Other ways to upload images

  1. Upload images via the built-in drag & drop mechanism. Simply click the file you need to upload, drag it into the desired position in the editor and drop it. The upload will be done automatically!
  2. Paste URL to an image into content and it will be automatically displayed.

This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.

# How it works

Except for pasting URLs to images, all other solutions mentioned above require the image to be uploaded to a server. The server will then be responsible for providing the image URL used by CKEditor 5 to display the image in the document. The software that makes the image upload possible is called an upload adapter. It is a callback that tells the WYSIWYG editor how to send the file to the server. There are two main strategies for getting the image upload to work that you can adopt in your project:

  • Official upload adapters – There are several features providing upload adapters developed and maintained by the CKEditor team. Some of these are simple and only enable uploading, while some, like the CKBox asset manager, let you upload, browse, manage, and edit images. Pick the best one for your integration and let it handle the image upload in your project.
  • Custom upload adapters – You can also create your upload adapter from scratch using the open API architecture of CKEditor 5.

If you want to get a better look under the hood and learn more about the upload process, you can check out the “Custom image upload adapter” deep dive guide covering this topic.

# Official upload adapters

# CKBox

CKBox is the ultimate solution for not just image upload but also file management in CKEditor 5.

It is a modern file uploader with a clean interface, automatic support for responsive images, and top-notch UX. It also provides editing capabilities like cropping, rotating, or flipping.

Thanks to the native CKEditor 5 integration, CKBox supports drag and drop file upload as well as pasting images from the clipboard, Microsoft Word, or Google Docs.

With CKBox, users can upload files and categorize them into different groups. They can also change the way the files are displayed, for example, by setting the image thumbnail size or deciding how many files are shown on one page. Files can be uploaded, deleted, renamed, and tagged. File properties like dimensions, upload date, or size are also easily accessible and can be used to sort the file view alongside a regular search.

Learn how to use CKBox in your project.

# CKFinder

The CKFinder feature provides a bridge between the rich-text editor and CKFinder, a browser-based file uploader with server-side connectors (PHP, Java, and ASP.NET).

There are two ways you can integrate CKEditor 5 with CKFinder:

  • With the server-side connector only – In this scenario, images dropped or pasted into the editor are uploaded to the CKFinder server-side connector running on your server.
  • With both the server-side connector and the client-side file manager (recommended) – Images dropped and pasted into the editor are uploaded to the server (like in the first option). With access to the file manager, you can browse previously uploaded images, organize them, or edit them.

Learn how to integrate CKEditor 5 with CKFinder in your project.

# Simple adapter

The simple upload adapter allows uploading images to your server using the XMLHttpRequest API with a minimal editor configuration.

Learn how to use the simple upload adapter in CKEditor 5.

# Base64 adapter

The Base64 upload feature converts images inserted into the editor into Base64 strings in the editor output.

Please remember that while Base64 upload is an easy solution, it is also highly inefficient. The image file itself is kept as data in the database, generating a much heavier data load and higher transfer. We recommend using alternative ways to upload images into CKEditor 5.

Learn how to use Base64–encoded images in CKEditor 5.

# Implementing your own upload adapter

CKEditor 5 provides an open API that allows you to develop your upload adapters. Tailored to your project, a custom adapter will allow you to take full control over the upload process. This includes both sending the files to the server and passing the response from the server (for example, the URL to the saved file) back to the WYSIWYG editor.

Learn how to develop a custom upload adapter for CKEditor 5.