guideConfiguration options

When creating a CKBox instance, it is possible to pass various configuration options. Some of them are mandatory, while others allow customizing the component. Below, you can find the list of all available configuration options with live usage examples.

Please note that in this guide we focus on the configuration options available for developers at the code level. If you are looking for configuration options available for the administrator users, please refer to the Administration panel guide.

# List of configuration options

The table below presents a compact list of the available configuration options. Please click the option name to read about details and see a live usage example.

Option name Description
tokenUrl The URL of the token endpoint.
dialog Defines whether the CKBox instance should opn in dialog mode.
assets.onChoose The callback executed after choosing files.
categories.icons Allows setting custom icons for categories.
language The user interface language localization to use.
theme Theme of the user interface.
id Sets the instance ID.
serviceOrigin Sets the origin to use for the REST API.
assetsOrigin Sets the origin to use for assets hosting.

# tokenUrl

As you might have read in the Authentication guide, CKBox uses JWT tokens for authentication. These tokens must be somehow obtained by the CKBox frontend client, and this is where the tokenUrl option comes into place. Using the URL passed here, CKBox obtains the JWT token and attaches it to all the API HTTP requests that require authentication.

This option is mandatory. Your CKBox will not work unless the tokenUrl is configured and your token endpoint returns proper JWT tokens.

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url'
});

# dialog

This option allows opening CKBox in dialog mode. It takes a boolean value or a configuration object with the following attributes:

Attribute Description
width Dialog width in pixels.
height Dialog height in pixels.
onClose Callback executed after closing the dialog.
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: {
        width: 800,
        height: 600
    },
    assets: {
        // Callback executed after choosing assets
        onChoose: (assets) => {
            assets.forEach((asset) => {
                console.log(asset.getUrl());
            })
        }
    }
});

Click on the button below to open CKBox in dialog mode.

# assets.onChoose

Defines a callback executed after choosing files. If this option is defined, the Choose button will be visible in CKBox. After selecting assets and clicking the Choose button, a callback defined in assets.onChoose will receive an array of objects representing chosen assets.

Each asset object contains a data attribute with the following information about the asset:

Attribute Description
id Asset id.
name Asset file name.
extension Asset file extension.
categoryId Category ID the asset belongs to.
size Asset file size in bytes.
uploadedAt Date the asset has been uploaded.
metadata Metadata of the asset. This object is format specific, i.e. for images it contains information about picture width and height in pixels.

Asset objects offer a couple of helper methods:

Method Description
.getUrl() Returns a URL of the asset. The resource at the URL is cached on the CDN.
.getResponsiveImageUrl(width, [height], [format]) If the asset is an image in a supported format, this method returns a URL of the image with requested dimensions. The width and height parameters define the bounding box the resized version of the image should fit into. The third parameter, format, is optional – by default images are rescaled to webp. Other supported formats are jpeg, png, bmp, tiff, gif and webp. The rescaled image at the URL is cached on the CDN.
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: true,
    assets: {
        // Callback executed after choosing assets
        onChoose: (assets) => {
            assets.forEach((asset) => {
                console.log(asset.getUrl());
            })
        }
    }
});

Click the button below to open CKBox in the dialog mode. URLs of the chosen files will be logged in the console.

# categories.icons

Allows setting custom icons for categories. This option takes an object with categories and icons that should be used instead of the default ones.
Categories can be defined using either their name or id (the id of the category can be obtained in the administration panel). Icons should be defined as strings containing the SVG images, or as React components.

The category can be referenced either by its name or by ID. When referencing the category by its name, you will have to update this configuration if the category name is changed. Referencing the category by ID is a more bulletproof solution because the category ID remains always the same. The category ID can be found in the Asset categories section of the administration panel.

Administration panel - category ID.

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: true,
    categories: {
        icons: {
            Images: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M12.395 2.553a1 1 0 00-1.45-.385c-.345.23-.614.558-.822.88-.214.33-.403.713-.57 1.116-.334.804-.614 1.768-.84 2.734a31.365 31.365 0 00-.613 3.58 2.64 2.64 0 01-.945-1.067c-.328-.68-.398-1.534-.398-2.654A1 1 0 005.05 6.05 6.981 6.981 0 003 11a7 7 0 1011.95-4.95c-.592-.591-.98-.985-1.348-1.467-.363-.476-.724-1.063-1.207-2.03zM12.12 15.12A3 3 0 017 13s.879.5 2.5.5c0-1 .5-4 1.25-4.5.5 1 .786 1.293 1.371 1.879A2.99 2.99 0 0113 13a2.99 2.99 0 01-.879 2.121z" /></svg>',
            // Category can be referenced by ID
            // 'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': '<svg...'
        }
    }
});

Click the button below to open the CKBox instance with a fancy flame icon set for the Images category.

# language

Configures the language to use in the CKBox instance. Please note that if you want to use a language other than English, you must include the appropriate language resource on your webpage:

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

To read more about the supported languages, please refer to the Localization guide.

In the example below, CKBox is configured to use Spanish.

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    language: 'es'
});

# theme

Configures theme to use.

To read more about theming options available in CKBox, please refer to Theming guide.

In the example below, CKBox is configured to use the dark theme.

<link rel="stylesheet" href="https://cdn.ckbox.io/CKBox/1.2.1/styles/themes/dark.css">
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    theme: 'dark'
});

# id

Sets the instance ID. This option is useful if you have multiple instances of CKBox on your webpage. By default, all the instances will share some parts of the data, e.g. user display options stored in the browser’s local storage. If CKBox instances have different id-s assigned, their user display options will be stored separately.

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    id: 'instance1'
});

# serviceOrigin

Sets the origin to use for the REST API if CKBox backend is an own-hosted on-premises installation.

This option should be set only if you host the CKBox backend on your own. It should not be present if you use CKBox in the SaaS version.

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    serviceOrigin: 'https://api.example.com'
});

# assetsOrigin

Sets the origin to use for asset URL-s if CKBox backend is an own-hosted on-premises installation.

This option should be set only if you host the CKBox backend on your own. It should not be present if you use CKBox in the SaaS version.

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    serviceOrigin: 'https://assets.example.com'
});