category: features-image-upload menu-title: Simple upload adapter
The {@link module:upload/adapters/simpleuploadadapter~SimpleUploadAdapter simple upload adapter} plugin allows uploading images to your server using the XMLHttpRequest API with a minimal editor configuration.
See the Server–side configuration section to learn about the requirements your server–side application must meet to support this upload adapter.
Check out the comprehensive {@link features/image-upload Image upload overview} to learn about other ways to upload images into CKEditor 5.
The {@link module:upload/adapters/simpleuploadadapter~SimpleUploadAdapter simple upload adapter} plugin is not available out–of–the–box in any of {@link builds/guides/overview#available-builds official editor builds}. Check out the {@link builds/guides/integration/installing-plugins "Installing plugins"} guide to learn more.
First, install the @ckeditor/ckeditor5-upload package:
npm install --save @ckeditor/ckeditor5-upload
Add the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadAdapter SimpleUploadAdapter} to your plugin list and configure the feature. For instance:
import SimpleUploadAdapter from '@ckeditor/ckeditor5-upload/src/adapters/simpleuploadadapter';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ SimpleUploadAdapter, ... ],
toolbar: [ ... ],
simpleUpload: {
// Feature configuration.
}
} )
.then( ... )
.catch( ... );
Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
The client side of this feature is configurable using the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig config.simpleUpload} object.
import SimpleUploadAdapter from '@ckeditor/ckeditor5-upload/src/adapters/simpleuploadadapter';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ SimpleUploadAdapter, ... ],
toolbar: [ ... ],
simpleUpload: {
// The URL that the images are uploaded to.
uploadUrl: 'http://example.com',
// Enable the XMLHttpRequest.withCredentials property.
withCredentials: true,
// Headers sent along with the XMLHttpRequest to the upload server.
headers: {
'X-CSRF-TOKEN': 'CSRF-Token',
Authorization: 'Bearer <JSON Web Token>'
}
}
} )
.then( ... )
.catch( ... );
The allowed file types that can be uploaded should actually be configured in two places:
Use the {@link module:image/imageupload~ImageUploadConfig#types image.upload.types} configuration option to define the allowed image MIME types that can be uploaded to CKEditor 5.
By default, users are allowed to upload jpeg, png, gif, bmp, webp and tiff files, but you can customize this behavior to accept, for example, SVG files.
It is up to you to implement any filtering mechanisms on your server in order to restrict the types of images that are allowed to be uploaded.
To use this upload adapter, you must provide a server–side application that will handle the uploads and communicate with the editor, as described in the following sections.
When the image upload process is initiated, the adapter sends a POST request under {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig#uploadUrl config.simpleUpload.uploadUrl}.
You can send additional headers along with the XMLHttpRequest to the upload server, e.g. to authenticate the user, using the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig#uploadUrl config.simpleUpload.headers} object.
If you use the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig#withCredentials config.simpleUpload.withCredentials} configuration, you may need some extra HTTP headers for the cross–site request to work properly.
The responseType of the request is always json. See the Successful upload and Error handling sections to learn more.
If the upload is successful, the server should return:
An object containing the url property which points to the uploaded image on the server:
{
"url": "https://example.com/images/foo.jpg"
}
Or an object with the urls property, if you want to use responsive images and the server supports it:
{
"urls": {
"default": "https://example.com/images/foo.jpg",
"800": "https://example.com/images/foo-800.jpg",
"1024": "https://example.com/images/foo-1024.jpg",
"1920": "https://example.com/images/foo-1920.jpg"
}
}
The "default" URL will be used in the src attribute of the image in the rich-text editor content. Other URLs will be used in the srcset attribute, allowing the web browser to select the best one for the geometry of the viewport.
The URL(s) in the server response are used:
If something went wrong, the server must return an object that contains the error property. This will terminate the upload in the editor, e.g. allowing the user to select another image if the previous one was too big or did not meet some other validation criteria.
If the error object contains a message, it will be passed to the {@link module:ui/notification/notification~Notification#showWarning editor notification system} and displayed to the user. For the convenience of the users, use clear and possibly specific error messages.
{
"error": {
"message": "The image upload failed because the image was too big (max 1.5MB)."
}
}
If the message property is missing in the error object, the {@link module:ui/notification/notification~Notification#showWarning editor notification system} will display the default "Couldn't upload file: [filename]." message.
This upload adapter will notify users about the file upload progress out–of–the–box.
Check out the comprehensive {@link features/image-upload Image upload overview} to learn more about different ways of uploading images in CKEditor 5.
See the {@link features/image Image feature} guide to find out more about handling images in CKEditor 5 WYSIWYG editor.
The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-upload.