CKBox file manager

CKBox is a dedicated asset manager and management platform service that provides a comprehensive digital asset management experience for CKEditor 5.

It handles file uploads and significantly reduces the effort required to build a complete modern editing solution that supports optimized and responsive images. Functionally, CKBox replaces the basic CKEditor 5 image upload feature by integrating a comprehensive file manager.

Demo

To upload a file using CKBox, use the open file manager toolbar button . You can choose more than one file at a time. Use the edit image button from either the main toolbar or the image contextual toolbar to edit the selected image.

Note that the image toolbar button will now also upload images right into the CKBox file manager and you can drag and drop them, too. You can then access the files from the management panel.

Uploading images

To upload an image using CKBox, do the following:

Use the file manager toolbar button to open the CKBox dialog.
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.

Another way to upload images is 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!

Uploading non-embeddable files

Non-embeddable files (like PDFs) are inserted as links. To upload a PDF file, do the following:

Use the file manager toolbar button to open the CKBox dialog.
Select a PDF and click the Choose button.

A link to the file will appear in the content.

Editing images

Use the image contextual toolbar to invoke the CKBox editing pane right from the editor.

The panorama of Warsaw — Panorama of Warsaw downtown.

Images are embedded directly into the content, which you can drag around and resize. Non-embeddable files (like PDF files) are inserted as links.

You can also upload images by dragging them into your content. After you drag an image into the editor, it gets uploaded into the CKBox cloud storage and inserted into the content.

How CKBox enhances CKEditor 5

CKBox streamlines the entire media content lifecycle from uploading and storing to management and display. By integrating CKBox, you enhance editing and accelerate content creation for your team.

CKBox works natively with CKEditor 5. Implementation is straightforward, saving you time and money.

Before you start

Note

This is a premium feature. Contact us to receive an offer tailored to your needs.
You can also sign up for the CKEditor Premium Features 14-day free trial to test the feature.
If you already have a valid license, please log into your Customer Portal to access the feature settings.

Key features

CKEditor 5 Integration Capabilities	Details
Effortless Uploads	Enables drag and drop uploads of images and files directly into CKEditor 5, as well as image pasting from the clipboard, Word, and Google Docs.
Image Editing	Provides an intuitive image editor for basic operations such as cropping, resizing, and rotating. Basic editing capabilities (crop, resize, rotate, flip) are available directly from the image contextual toolbar for CKBox-served images.
Management UI	Adds a dedicated toolbar button to open the CKBox UI for managing and reusing uploaded files. Non-embeddable files (such as PDF) are inserted as links automatically.
Asset Separation	Supports multi-tenant workspaces to separate assets per user, document, or customer.
User Experience and SEO	CKBox simplifies the use of responsive images served from a CDN, improving loading times, boosting SEO, and increasing conversions.
Bandwidth Savings	Out-of-the-box support for the most modern image formats, CKBox can save up to 90% of bandwidth if your application does not yet support responsive images, or up to 34% compared to relying on responsive JPG/PNG images.
Security and Administration	Manage asset security and compliance using configurable permissions across workspaces, categories, and user groups.

With CKBox you no longer need to write server-side code to upload and scale images or manage uploaded files.

Hosting options

CKBox offers significant architectural flexibility, providing users with full control of their data by supporting diverse deployment scenarios. CKBox is available for both cloud (SaaS) and on-premises (self-hosted) installation:

Option	Benefits
SaaS	Offers hassle-free, maintenance-free usage. We manage the cloud infrastructure to keep it secure and up-to-date, perform regular backups of your files, ensure automatic scaling, and guarantee maximum security and high availability. Assets are served via a secure and blazing-fast CDN.
On-premises Option (Self-Hosted)	Allows you to host CKBox yourself. It can be installed anywhere, including AWS, Azure, Google Cloud, or your own data center. It runs with any Open Container runtime tool (for example: Kubernetes, Docker, OpenShift, Podman) and supports various storage types like S3, Azure Blob Storage, MySQL, Postgres, and local filesystem.

To find out more about CKBox, the brand-new file manager and image editor, visit the CKBox website and read the dedicated CKBox documentation page.

You can read more about the storage options in the dedicated CKBox Deployment guide.

Installation

CKBox offers two primary methods for loading the library: using a Content Delivery Network (CDN) for fast, script-based integration, or using a Package Manager (npm/yarn) for modern application bundles.

Method 1: Installation from CDN

The easiest way to load the CKBox library is to include the following <script> tag in your HTML header that points to the CKBox CDN, ensuring it loads before the rich text editor:

<script src="https://cdn.ckbox.io/ckbox/2.9.2/ckbox.js"></script>

When referencing the CKBox library via CDN, you must specify the version number (for example: 2.9.2 or latest).

Note

While the ability to use the shorthand latest tag instead of a specific version number is available, it is strongly advised against. The use of the latest tag may inadvertently introduce breaking changes into your application, which could cause your CKBox integration to stall unexpectedly.

Suppose you wish to change the default language of the CKBox, which supports over 40 official translations. In that case, you must ensure you load the corresponding translation file after loading the main CKBox library. For example, to load the Spanish translation (es):

<script src="https://cdn.ckbox.io/ckbox/2.9.2/ckbox.js"></script>
<script src="https://cdn.ckbox.io/ckbox/2.9.2/translations/es.js"></script>

Once imported, you can use it within your application:

<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/47.2.0/ckeditor5.css">
    </head>
    <body>
        <div id="editor"></div>
        <script src="https://cdn.ckeditor.com/ckeditor5/47.2.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.9.2/ckbox.js"></script>
        <script>
            const { ClassicEditor, LinkEditing, Image, ImageUpload, PictureEditing, CKBox, CKBoxImageEdit, CloudServices } = CKEDITOR;

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ LinkEditing, Image, PictureEditing, ImageUpload, CloudServices, CKBox, CKBoxImageEdit, /* ... */ ],
                    toolbar: ['imageUpload', 'ckbox', 'ckboxImageEdit', /* ... */ ], // Depending on your preference.
                    ckbox: {
                        // Configuration.
                    }
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</html>

Method 2: Installation from npm

For applications using modern bundling tools (such as Webpack or Vite) and package managers (npm, yarn, pnpm), CKBox components should be installed as dependencies and imported into your CKEditor 5 build.

Note

CKBox is a premium feature. Using the self-hosted distribution channel (npm) requires having an appropriate commercial plan or a Custom plan that permits the use of the editor via npm or a ZIP package.

You can sign up for the CKEditor Premium Features 14-day free trial to test the feature. If you already have a license, you should log into your Customer Portal Dashboard to access feature settings and credentials.

First, install the necessary dependencies:

npm install ckeditor5 ckbox

Once the packages are installed, you can import the necessary modules directly into your application code and use them within your application:

import { ClassicEditor, Image, ImageUpload, LinkEditing, PictureEditing, CKBox, CKBoxImageEdit, CloudServices } from 'ckeditor5';
import * as ckbox from 'ckbox';
import 'ckeditor5/ckeditor5.css';
import 'ckbox/dist/styles/ckbox.css';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ LinkEditing, Image, PictureEditing, ImageUpload, CloudServices, CKBox, CKBoxImageEdit, /* ... */ ],
        toolbar: [ 'imageUpload', 'ckbox', 'ckboxImageEdit', /* ... */ ], // Depending on your preference.
        ckbox: {
            // Configuration.
            tokenUrl: '<YOUR_TOKEN_URL>'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Configuration

The feature can be configured via the config.ckbox object.

Defining upload categories

By default, the CKBox feature maps the uploaded image type to the category configured on the cloud service. You can override this behavior and provide your own mappings via the config.ckbox.defaultUploadCategories configuration option. It is an object where the keys define categories, and their values are the types of images that will be uploaded to these categories. The categories might be referenced either by their name or by their ID. Referencing by ID is future-proof because it will not require configuration changes when a category name changes.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            defaultUploadCategories: {
                Bitmaps: [ 'bmp' ],
                Pictures: [ 'jpg', 'jpeg' ],
                Scans: [ 'png', 'tiff' ],
                // The category below is referenced by its ID.
                'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': [ 'gif' ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

If you define your own upload category mappings for a particular image type, only your first found category will be taken into account while finding the appropriate category for the uploaded image. Category mappings configured on the server will not be searched in that case. The image will not be uploaded (and hence inserted into the editor) in the following cases:

If you have defined your own category mapping in defaultUploadCategories for the uploaded image type:
- The category does not exist on the server.
- The category exists on the server, but the server configuration does not allow the uploaded image type.
If you have not defined your own category mapping in defaultUploadCategories for the uploaded image type:
- There is no category mapping for the uploaded image type on the server.

Defining default upload workspace

The CKBox workspaces provide a convenient solution for achieving data isolation and user separation within CKBox. With workspaces, you can easily create separate storage and data spaces, giving you precise control over assigning specific users, user groups, or tenants to each workspace.

If the user is assigned to more than one workspace, by default all the files uploaded directly from CKEditor are located in the first workspace in the list of workspaces allowed in the user’s JWT token. This corresponds to uploads through drag and drop into the editor area, pasting images from the clipboard, or images uploaded using the Image feature. If you would like to define a specific workspace for files uploaded this way, you can define its ID in the defaultUploadWorkspaceId option. After that, all the files uploaded directly from CKEditor will be placed in the specified workspace.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            tokenUrl: 'https://your.token.url',
            // Sample workspace referenced by its ID.
            defaultUploadWorkspaceId: [ 'pHUSQFj_QIvc' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

You can obtain the list of available workspaces using the Workspaces REST API.

Adding the ID for inserted assets

After choosing an asset from the CKBox dialog, it is inserted into the editor content with a unique data-ckbox-resource-id attribute. If you want to disable it and do not want to add this attribute, set the config.ckbox.ignoreDataId option to true:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            ignoreDataId: true
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Changing the language

By default, the CKBox dialog takes the current language from the editor. If you want to use a different language, you can set the language code in the config.ckbox.language option:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            language: 'es'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Also, make sure to include the translation file after loading the CKBox library:

<script src="https://cdn.ckbox.io/ckbox/2.9.2/ckbox.js"></script>
<script src="https://cdn.ckbox.io/ckbox/2.9.2/translations/es.js"></script>

Providing the token URL

The CKBox feature requires the token endpoint URL configured in the config.ckbox.tokenUrl key. If not explicitly provided, the token URL from config.cloudServices.tokenUrl is used instead. If both are provided, the token URL defined in config.ckbox.tokenUrl takes precedence over the config.cloudServices.tokenUrl.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            tokenUrl: 'https://example.com/cs-token-endpoint'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Configuring the API service

If you host the cloud service in your environment, you should configure the base URL of the API service via the config.ckbox.serviceOrigin option:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            serviceOrigin: 'https://example.com/'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Editing external images

If you want to allow CKBox to edit external images, not hosted by the file manager (for example, pasted via URL) you need to whitelist the URLs of the images. You can do this using the config.ckbox.allowExternalImagesEditing option:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        ckbox: {
            allowExternalImagesEditing: [ 'origin', /^cksource.com/ ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

The image is editable if this option is:

a regular expression and it matches the image URL, or
a custom function that returns true for the image URL, or
origin literal and the image URL is from the same origin, or
an array of the above and the image URL matches one of the array elements.

Warning

Make sure that the domains you whitelist have CORS enabled, allowing to fetch the images from that domain. If you whitelist a domain without proper CORS configuration, you will get errors from the editor.

Common API

The CKBox plugin registers:

The 'ckbox' UI button component for CKBox asset manager.
The 'ckbox' command implemented by the CKBoxCommand.

You can open CKBox by executing the following code:

editor.execute( 'ckbox' );

If you want to use the CKBox editing capabilities straight from the editor, the plugin will also register the following:

The 'ckboxImageEdit' UI button component for the CKBox image editor.
The 'ckboxImageEdit' command implemented by the CKBoxImageEdit.

Note

We recommend using the official CKEditor 5 inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

REST API

The CKBox REST API allows managing files and configuration of the drive. Read the REST API documentation to find out how to employ it in your implementation.

What’s next

Be sure to check out the comprehensive Image upload overview guide to learn more about different ways of uploading images in CKEditor 5.

See the image feature guide to find out more about handling images in CKEditor 5 in general.

Warning

Need more functionality? Take a survey and help us develop CKBox to suit your needs better!

Contribute

The source code of the feature is available on GitHub at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-ckbox.

CKBox file manager

Unlock this feature with selected CKEditor Plans

Demo

Uploading images

Uploading non-embeddable files

Editing images

How CKBox enhances CKEditor 5

Before you start

Key features

Hosting options

Installation

Method 1: Installation from CDN

Method 2: Installation from npm

Configuration

Defining upload categories

Defining default upload workspace

Adding the ID for inserted assets

Changing the language

Providing the token URL

Configuring the API service

Editing external images

Common API

REST API

What’s next

Contribute