CKEditor Ecosystem Documentation
Search
Contribute to this guide
Home/CKEditor 5/Getting started

Loading CDN resources

Loading CKEditor 5 and its plugins from a CDN requires adding the necessary script and style sheet tags to the <head> of your page. In some environments, this can be easily done manually by following the CDN for Vanilla JavaScript guide.

However, other environments may require more work. It is especially true if you want to load some resources conditionally or dynamically or need to wait for the resources to be loaded before using them.

For this reason, we provide the useCKEditorCloud and loadCKEditorCloud helper functions to make this process easier. These functions will handle adding the necessary script and style sheet tags to your page, ensure that the resources are only loaded once, and provide access to the data exported by them. This way you can load CKEditor 5 and its plugins from a CDN without worrying about the technical details.

If you use our React or Vue.js 3+ integrations, see the Using the useCKEditorCloud function section. Otherwise, see the Using the loadCKEditorCloud function section.

# Using the useCKEditorCloud function

Our React and Vue.js 3+ integrations export a helper function named useCKEditorCloud to help you load CDN resources. These helpers are only small wrappers around the loadCKEditorCloud function but are designed to better integrate with the specific framework, its lifecycle, and reactivity mechanisms.

Here is an example of how you can use useCKEditorCloud:

const cloud = useCKEditorCloud( {
    version: '44.0.0',
    premium: true
} );

This will add the necessary script and style sheet tags to the page’s <head> and update the internal state to reflect the loading status. Depending on the framework, the useCKEditorCloud function may return different values. Please refer to the documentation of the specific integration for more details.

Regardless of the framework used, the useCKEditorCloud functions always accept the same options, which are described in the loadCKEditorCloud function options section.

# Using the loadCKEditorCloud function

To use the loadCKEditorCloud helper, you need to install the following package:

npm install @ckeditor/ckeditor5-integrations-common

Then you can use the loadCKEditorCloud function like this:

import { loadCKEditorCloud } from '@ckeditor/ckeditor5-integrations-common';

const { CKEditor, CKEditorPremiumFeatures } = await loadCKEditorCloud( {
    version: '44.0.0',
    premium: true
} );

The loadCKEditorCloud function returns a promise that resolves to an object in which each key contains data of the corresponding CDN resources. The exact object shape depends on the options passed to the function.

The options accepted by the loadCKEditorCloud function are described in The loadCKEditorCloud function options section.

# The loadCKEditorCloud function options

The loadCKEditorCloud function (and useCKEditorCloud functions which are small wrappers around it) accepts an object with the following properties:

  • version (required) – The version of CKEditor 5 and premium features (if premium option is set to true) to load.
  • translations (optional) – An array of language codes to load translations for.
  • premium (optional) – A Boolean value that indicates whether to load premium plugins. [1]
  • ckbox (optional) – Configuration for loading CKBox integration. [1]
  • plugins (optional) – Configuration for loading additional plugins. The object should have the global plugin name as keys and the plugin configuration as values. [1]
  • injectedHtmlElementsAttributes (optional) – An object with attributes that will be added to the <script> and <link> tags that are injected into the page. This can be used to add attributes like integrity or crossorigin to the tags. By default, it is set to { crossorigin: 'anonymous' }.

[1] Using this option will result in additional network requests for JavaScript and CSS assets. Make sure to only use this option when you need it.

Here is an example showing all the available options:

{
    version: '44.0.0',
    translations: [ 'es', 'de' ],
    premium: true,
    ckbox: {
        version: '2.5.1',
        theme: 'lark' // Optional, default 'lark'.
    },
    plugins: {
        ThirdPartyPlugin: [
            'https://cdn.example.com/plugin.umd.js',
            'https://cdn.example.com/plugin.css'
        ],
        AnotherPlugin: () => import( './path/to/plugin.umd.js' ),
        YetAnotherPlugin: {
            scripts: [ 'https://cdn.example.com/plugin.umd.js' ],
            stylesheets: [ 'https://cdn.example.com/plugin.css' ],

            // Optional, if it's not passed then the name of the plugin will be used.
            checkPluginLoaded: () => window.PLUGIN_NAME
        }
    }
}

Note that unless the checkPluginLoaded callback is used, the keys in the plugins object must match the names of the global object used by the plugins. As shown in the example above, we used the checkPluginLoaded to be able to access the plugin using the YetAnotherPlugin key, while the plugin itself assigns to the window.PLUGIN_NAME property.

With this configuration, the object returned by this function will have the following properties:

  • CKEditor – The base CKEditor 5 library.
  • CKEditorPremiumFeatures – Premium features for CKEditor 5. This option is only available when premium is set to true.
  • CKBox – The CKBox integration. This option is only available when the ckbox option is provided.
  • ThirdPartyPlugin – The custom plugin registered in the plugins option.
  • AnotherPlugin – The custom plugin registered in the plugins option.
  • YetAnotherPlugin – The custom plugin registered in the plugins option.