How does the image upload work?

Before you can create your custom upload adapter, you should learn about the image upload process in CKEditor 5. The whole process consists of the following steps:

1. First, an image (or images) needs to get into the rich-text editor content. There are many ways to do that, for instance:

   • pasting an image from the clipboard,
   • dragging a file from the file system,
   • selecting an image through a file system dialog.

   The images are intercepted by the image upload plugin (which is enabled in all official editor builds).

2. For every image, the image upload plugin creates an instance of a file loader.

   • The role of the file loader is to read the file from the disk and upload it to the server by using the upload adapter.
   • The role of the upload adapter is, therefore, to securely send the file to the server and pass the response from the server (for example, the URL to the saved file) back to the file loader (or handle an error, if there was one).

3. While the images are being uploaded, the image upload plugin:

   • Creates placeholders for these images.
   • Inserts them into the editor.
   • Displays the progress bar for each of them.
   • When an image is deleted from the editor content before the upload finishes, it aborts the upload process.

4. Once the file is uploaded, the upload adapter notifies the editor about this fact by resolving its Promise. It passes the URL (or URLs in case of responsive images) to the image upload plugin which replaces the src and srcset attributes of the image placeholder in the editor content.

This is just an overview of the image upload process. Actually, the whole thing is more complicated. For instance, images can be copied and pasted within the WYSIWYG editor (while the upload takes place) and all potential upload errors must be handled, too. The good news is these tasks are handled transparently by the image upload plugin so you do not have to worry about them.

To sum up, for the image upload to work in the rich-text editor, two conditions must be true:

• The image upload plugin must be enabled in the editor. It is enabled by default in all official builds, but if you are customizing CKEditor 5, do not forget to include it.

• The upload adapter needs to be defined. This can be done by using (enabling and configuring):

  • One of the existing upload adapters.
  • Your custom upload adapter and handling uploaded files on your server backend.

The anatomy of the adapter

A custom upload adapter allows you to take full control over the process of sending the files to the server as well as passing the response from the server back to the rich-text editor.

Any upload adapter, whether an image upload adapter or a generic file upload adapter, must implement the UploadAdapter interface to work, that is, it must bring its own upload() and abort() methods.

• The upload() method must return a promise:
  • resolved by a successful upload with an object containing information about the uploaded file (see the section about responsive images to learn more),
  • rejected because of an error, in which case nothing is inserted into the content.
• The abort() method must allow the editor to stop the upload process. It is necessary, for instance, when the image was removed from the content by the user before the upload finished or the editor instance was destroyed.

In its simplest form, a custom adapter implementing the UploadAdapter interface will look as follows. Note that server.upload(), server.onUploadProgress() and server.abortUpload() should be replaced by specific implementations (dedicated for your application) and onl