Configuration

---

---

⚠⚠ ⚠⚠ ⚠⚠

This wiki served in the early days of CKEditor 5 development and can be severely outdated.

Refer to the official CKEditor 5 documentation for up-to-date information.

---

---

In CKEditor 5, each editor instance contains configurations which impact on the instance behavior.

Case-Insensitive Names

Configuration names are case-insensitive, to avoid issues with minor typos on case.

We prefer lowerCamelCase, like resize.minHeight, but end users will be able to do things like Resize.MinHeight or resize.minheight without problems.

Setting Editor Configurations

Configuration are set to editor instances in the moment of their creation:

CKEDITOR.create( '#content', {
    creator: 'inline',
    language: 'pl',
    resize: {
        minHeight: 300,
        maxHeight: 800
    }
} );

After creation, it is not possible to set configurations in the editor. Although it is possible to call editor.config.set(), it will always throw an error.

Getting Configuration Values

To retrieve a configuration value, call editor.config.get():

var creator = editor.config.get( 'creator' );
var lang = editor.config.get( 'language' );
var minHeight = editor.config.get( 'resize.minHeight' );

It is also possible to work with subsets of the configuration:

var resize = editor.config.get( 'resize' );
var maxHeight = resize.get( 'maxHeight' );

Setting Configuration Defaults Globally

It is possible to set default value of configurations that will impact on all editor instances by manipulating the CKEDITOR.config object:

CKEDITOR.config.set( 'language', 'pl' )
CKEDITOR.config.set( 'resize.minHeight', 400 );

If an editor instance will not have such configurations set or defined into itself, it will then use the ones from the global defaults.

Defining Configurations

Developers bringing features to CKEditor, usually through plugins, should "define" configurations introduced by their code.

To define configuration, simply call config.define(). For example:

CKEDITOR.config.define( 'language', 'en' );

editor.config.define( {
    resize: {
        minHeight: 150,
        maxHeight: null
    }
} );

Note that configurations defined in an editor instance will be valid just for it. Calls for CKEDITOR.config.define() will be available for all editors.

Plugin developers have a "shortcut" to define configurations, by including the config property into their plugin class. Configurations available there will be automatically defined into editors using such plugins.

Defining configurations brings the following benefits:

• It sets default values for the configurations.
• It makes it possible to perform validation on configuration names.

Validation is not performed by the editor by default but it could be done by additional plugins or future editor features.