@ckeditor/ckeditor5-core

constructor

constructor(editor: Editor);

• Creates a new Command instance.

  Parameter editor

  The editor on which this command will be used.

property affectsData

affectsData: boolean;

• A flag indicating whether a command execution changes the editor data or not.

  Commands with affectsData set to false will not be automatically disabled in the and with restricted user write permissions.

  **Note:** You do not have to set it for your every command. It is true by default.

  true

property editor

readonly editor: Editor;

• The editor on which this command will be used.

property isEnabled

isEnabled: boolean;

• Flag indicating whether a command is enabled or disabled. A disabled command will do nothing when executed.

  A given command class should control this value by overriding the method.

  It is possible to disable a command "from outside" using method.

  Modifiers

  • @readonly

property value

value: {};

• The value of the command. A given command class should define what it represents for it.

  For example, the 'bold' command's value indicates whether the selection starts in a bolded text. And the value of the 'link' command may be an object with link details.

  It is possible for a command to have no value (e.g. for stateless actions such as 'uploadImage').

  A given command class should control this value by overriding the method.

  Modifiers

  • @readonly

method clearForceDisabled

clearForceDisabled: (id: string) => void;

• Clears forced disable previously set through . See .

  Parameter id

  Unique identifier, equal to the one passed in call.

method destroy

destroy: () => void;

• Destroys the command.

method execute

execute: (...args: Array<unknown>) => unknown;

• Executes the command.

  A command may accept parameters. They will be passed from to the command.

  The execute() method will automatically abort when the command is disabled ( is false). This behavior is implemented by a high priority listener to the event.

  In order to see how to disable a command from "outside" see the documentation.

  This method may return a value, which would be forwarded all the way down to the .

  execute

method forceDisabled

forceDisabled: (id: string) => void;

• Disables the command.

  Command may be disabled by multiple features or algorithms (at once). When disabling a command, unique id should be passed (e.g. the feature name). The same identifier should be used when the command. The command becomes enabled only after all features .

  Disabling and enabling a command:

  command.isEnabled; // -> true
  command.forceDisabled( 'MyFeature' );
  command.isEnabled; // -> false
  command.clearForceDisabled( 'MyFeature' );
  command.isEnabled; // -> true

  Command disabled by multiple features:

  command.forceDisabled( 'MyFeature' );
  command.forceDisabled( 'OtherFeature' );
  command.clearForceDisabled( 'MyFeature' );
  command.isEnabled; // -> false
  command.clearForceDisabled( 'OtherFeature' );
  command.isEnabled; // -> true

  Multiple disabling with the same identifier is redundant:

  command.forceDisabled( 'MyFeature' );
  command.forceDisabled( 'MyFeature' );
  command.clearForceDisabled( 'MyFeature' );
  command.isEnabled; // -> true

  **Note:** some commands or algorithms may have more complex logic when it comes to enabling or disabling certain commands, so the command might be still disabled after was used.

  Parameter id

  Unique identifier for disabling. Use the same id when the command.

method refresh

refresh: () => void;

• Refreshes the command. The command should update its and properties in this method.

  This method is automatically called when .

constructor

constructor(config?: ContextConfig);

• Creates a context instance with a given configuration.

  Usually not to be used directly. See the static method.

  Parameter config

  The context configuration.

property builtinPlugins

static builtinPlugins: PluginConstructor<Editor | Context>[];

• An array of plugins built into the Context class.

  It is used in CKEditor 5 builds featuring Context to provide a list of context plugins which are later automatically initialized during the context initialization.

  They will be automatically initialized by Context unless config.plugins is passed.

  // Build some context plugins into the Context class first.
  Context.builtinPlugins = [ FooPlugin, BarPlugin ];
  
  // Normally, you need to define config.plugins, but since Context.builtinPlugins was
  // defined, now you can call create() without any configuration.
  Context
  	.create()
  	.then( context => {
  		context.plugins.get( FooPlugin ); // -> An instance of the Foo plugin.
  		context.plugins.get( BarPlugin ); // -> An instance of the Bar plugin.
  	} );

  See also and .

property config

readonly config: Config<ContextConfig>;

• Stores all the configurations specific to this context instance.

property defaultConfig

static defaultConfig: ContextConfig;

• The default configuration which is built into the Context class.

  It is used in CKEditor 5 builds featuring Context to provide the default configuration options which are later used during the context initialization.

  Context.defaultConfig = {
  	foo: 1,
  	bar: 2
  };
  
  Context
  	.create()
  	.then( context => {
  		context.config.get( 'foo' ); // -> 1
  		context.config.get( 'bar' ); // -> 2
  	} );
  
  // The default options can be overridden by the configuration passed to create().
  Context
  	.create( { bar: 3 } )
  	.then( context => {
  		context.config.get( 'foo' ); // -> 1
  		context.config.get( 'bar' ); // -> 3
  	} );

  See also and .

property editors

readonly editors: Collection<Editor>;

• A list of editors that this context instance is injected to.

property locale

readonly locale: Locale;

property plugins

readonly plugins: PluginCollection<Editor | Context>;

• The plugins loaded and in use by this context instance.

property t

readonly t: LocaleTranslate;

• Shorthand for .

method create

static create: (config?: ContextConfig) => Promise<Context>;

• Creates and initializes a new context instance.

  const commonConfig = { ... }; // Configuration for all the plugins and editors.
  const editorPlugins = [ ... ]; // Regular plugins here.
  
  Context
  	.create( {
  		// Only context plugins here.
  		plugins: [ ... ],
  
  		// Configure the language for all the editors (it cannot be overwritten).
  		language: { ... },
  
  		// Configuration for context plugins.
  		comments: { ... },
  		...
  
  		// Default configuration for editor plugins.
  		toolbar: { ... },
  		image: { ... },
  		...
  	} )
  	.then( context => {
  		const promises = [];
  
  		promises.push( ClassicEditor.create(
  			document.getElementById( 'editor1' ),
  			{
  				editorPlugins,
  				context
  			}
  		) );
  
  		promises.push( ClassicEditor.create(
  			document.getElementById( 'editor2' ),
  			{
  				editorPlugins,
  				context,
  				toolbar: { ... } // You can overwrite the configuration of the context.
  			}
  		) );
  
  		return Promise.all( promises );
  	} );

  Parameter config

  The context configuration.

  Returns

  A promise resolved once the context is ready. The promise resolves with the created context instance.

method destroy

destroy: () => Promise<unknown>;

• Destroys the context instance and all editors used with the context, releasing all resources used by the context.

  Returns

  A promise that resolves once the context instance is fully destroyed.

method initPlugins

initPlugins: () => Promise<LoadedPlugins>;

• Loads and initializes plugins specified in the configuration.

  Returns

  A promise which resolves once the initialization is completed, providing an array of loaded plugins.

constructor

constructor(context: Editor | Context);

• Creates a new plugin instance.

property context

readonly context: ContextInterface;

• The context or editor instance.

property isContextPlugin

static readonly isContextPlugin: boolean;

method destroy

destroy: () => void;

constructor

constructor(config?: EditorConfig);

• Creates a new instance of the editor class.

  Usually, not to be used directly. See the static method.

  Parameter config

  The editor configuration.

property builtinPlugins

static builtinPlugins?: PluginConstructor<Editor>[];

• An array of plugins built into this editor class.

  It is used in CKEditor 5 builds to provide a list of plugins which are later automatically initialized during the editor initialization.

  They will be automatically initialized by the editor, unless listed in config.removePlugins and unless config.plugins is passed.

  // Build some plugins into the editor class first.
  ClassicEditor.builtinPlugins = [ FooPlugin, BarPlugin ];
  
  // Normally, you need to define config.plugins, but since ClassicEditor.builtinPlugins was
  // defined, now you can call create() without any configuration.
  ClassicEditor
  	.create( sourceElement )
  	.then( editor => {
  		editor.plugins.get( FooPlugin ); // -> An instance of the Foo plugin.
  		editor.plugins.get( BarPlugin ); // -> An instance of the Bar plugin.
  	} );
  
  ClassicEditor
  	.create( sourceElement, {
  		// Do not initialize these plugins (note: it is defined by a string):
  		removePlugins: [ 'Foo' ]
  	} )
  	.then( editor => {
  		editor.plugins.get( FooPlugin ); // -> Undefined.
  		editor.config.get( BarPlugin ); // -> An instance of the Bar plugin.
  	} );
  
  ClassicEditor
  	.create( sourceElement, {
  		// Load only this plugin. It can also be defined by a string if
  		// this plugin was built into the editor class.
  		plugins: [ FooPlugin ]
  	} )
  	.then( editor => {
  		editor.plugins.get( FooPlugin ); // -> An instance of the Foo plugin.
  		editor.config.get( BarPlugin ); // -> Undefined.
  	} );

  See also .

property commands

readonly commands: CommandCollection;

• Commands registered to the editor.

  Use the shorthand method to execute commands:

  // Execute the bold command:
  editor.execute( 'bold' );
  
  // Check the state of the bold command:
  editor.commands.get( 'bold' ).value;

property config

readonly config: Config<EditorConfig>;

• Stores all configurations specific to this editor instance.

  editor.config.get( 'image.toolbar' );
  // -> [ 'imageStyle:block', 'imageStyle:side', '|', 'toggleImageCaption', 'imageTextAlternative' ]

property conversion

readonly conversion: Conversion;

• Conversion manager through which you can register model-to-view and view-to-model converters.

  See the documentation to learn how to add converters.

property data

readonly data: DataController;

• The . Used e.g. for setting and retrieving the editor data.

property defaultConfig

static defaultConfig?: EditorConfig;

• The default configuration which is built into the editor class.

  It is used in CKEditor 5 builds to provide the default configuration options which are later used during the editor initialization.

  ClassicEditor.defaultConfig = {
  	foo: 1,
  	bar: 2
  };
  
  ClassicEditor
  	.create( sourceElement )
  	.then( editor => {
  		editor.config.get( 'foo' ); // -> 1
  		editor.config.get( 'bar' ); // -> 2
  	} );
  
  // The default options can be overridden by the configuration passed to create().
  ClassicEditor
  	.create( sourceElement, { bar: 3 } )
  	.then( editor => {
  		editor.config.get( 'foo' ); // -> 1
  		editor.config.get( 'bar' ); // -> 3
  	} );

  See also .

property editing

readonly editing: EditingController;

• The . Controls user input and rendering the content for editing.

property id

readonly id: string;

property isReadOnly

isReadOnly: boolean;

• Defines whether the editor is in the read-only mode.

  In read-only mode the editor are disabled so it is not possible to modify the document by using them. Also, the editable element(s) become non-editable.

  In order to make the editor read-only, you need to call the method:

  editor.enableReadOnlyMode( 'feature-id' );

  Later, to turn off the read-only mode, call :

  editor.disableReadOnlyMode( 'feature-id' );

  Modifiers

  • @readonly

property keystrokes

readonly keystrokes: EditingKeystrokeHandler;

• An instance of the .

  It allows setting simple keystrokes:

  // Execute the bold command on Ctrl+E:
  editor.keystrokes.set( 'Ctrl+E', 'bold' );
  
  // Execute your own callback:
  editor.keystrokes.set( 'Ctrl+E', ( data, cancel ) => {
  	console.log( data.keyCode );
  
  	// Prevent the default (native) action and stop the underlying keydown event
  	// so no other editor feature will interfere.
  	cancel();
  } );

  Note: Certain typing-oriented keystrokes (like Backspace or Enter) are handled by a low-level mechanism and trying to listen to them via the keystroke handler will not work reliably. To handle these specific keystrokes, see the events fired by the (editor.editing.view.document).

property locale

readonly locale: Locale;

• The locale instance.

property model

readonly model: Model;

• The editor's model.

  The central point of the editor's abstract data model.

property plugins

readonly plugins: PluginCollection<Editor>;

• The plugins loaded and in use by this editor instance.

  editor.plugins.get( 'ClipboardPipeline' ); // -> An instance of the clipboard pipeline plugin.

property state

state: 'initializing' | 'ready' | 'destroyed';

• Indicates the editor life-cycle state.

  The editor is in one of the following states:

  * initializing – During the editor initialization (before ) finished its job. * ready – After the promise returned by the method is resolved. * destroyed – Once the method was called.

property t

readonly t: LocaleTranslate;

• Shorthand for .

  See Also

  • module:utils/locale~Locale#t

property ui

readonly ui: EditorUI;

• The editor UI instance.

method create

static create: (...args: Array<unknown>) => void;

• Creates and initializes a new editor instance.

  This is an abstract method. Every editor type needs to implement its own initialization logic.

  See the create() methods of the existing editor types to learn how to use them:

  * * * *

method destroy

destroy: () => Promise<unknown>;

• Destroys the editor instance, releasing all resources used by it.

  **Note** The editor cannot be destroyed during the initialization phase so if it is called while the editor , it will wait for the editor initialization before destroying it.

  destroy

  Returns

  A promise that resolves once the editor instance is fully destroyed.

method disableReadOnlyMode

disableReadOnlyMode: (lockId: string | symbol) => void;

• Removes the read-only lock from the editor with given lock ID.

  When no lock is present on the editor anymore, then the will be set to false.

  Parameter lockId

  The lock ID for setting the editor to the read-only state.

method enableReadOnlyMode

enableReadOnlyMode: (lockId: string | symbol) => void;

• Turns on the read-only mode in the editor.

  Editor can be switched to or out of the read-only mode by many features, under various circumstances. The editor supports locking mechanism for the read-only mode. It enables easy control over the read-only mode when many features wants to turn it on or off at the same time, without conflicting with each other. It guarantees that you will not make the editor editable accidentally (which could lead to errors).

  Each read-only mode request is identified by a unique id (also called "lock"). If multiple plugins requested to turn on the read-only mode, then, the editor will become editable only after all these plugins turn the read-only mode off (using the same ids).

  Note, that you cannot force the editor to disable the read-only mode if other plugins set it.

  After the first enableReadOnlyMode() call, the will be set to true:

  editor.isReadOnly; // `false`.
  editor.enableReadOnlyMode( 'my-feature-id' );
  editor.isReadOnly; // `true`.

  You can turn off the read-only mode ("clear the lock") using the method:

  editor.enableReadOnlyMode( 'my-feature-id' );
  // ...
  editor.disableReadOnlyMode( 'my-feature-id' );
  editor.isReadOnly; // `false`.

  All "locks" need to be removed to enable editing:

  editor.enableReadOnlyMode( 'my-feature-id' );
  editor.enableReadOnlyMode( 'my-other-feature-id' );
  // ...
  editor.disableReadOnlyMode( 'my-feature-id' );
  editor.isReadOnly; // `true`.
  editor.disableReadOnlyMode( 'my-other-feature-id' );
  editor.isReadOnly; // `false`.

  Parameter lockId

  A unique ID for setting the editor to the read-only state.

method execute

execute: <TName extends string>(
    commandName: TName,
    ...commandParams: Parameters<CommandsMap[TName]['execute']>
) => ReturnType<CommandsMap[TName]['execute']>;

• Executes the specified command with given parameters.

  Shorthand for:

  editor.commands.get( commandName ).execute( ... );

  Parameter commandName

  The name of the command to execute.

  Parameter commandParams

  Command parameters.

  Returns

  The value returned by the .

method focus

focus: () => void;

• Focuses the editor.

  **Note** To explicitly focus the editing area of the editor, use the method of the editing view.

  Check out the section of the guide to learn more.

method initPlugins

initPlugins: () => Promise<LoadedPlugins>;

• Loads and initializes plugins specified in the configuration.

  Returns

  A promise which resolves once the initialization is completed, providing an array of loaded plugins.

method execute

execute: (...args: Array<unknown>) => unknown;

• Executes the first enabled command which has the highest priority of all registered child commands.

  Returns

  The value returned by the .

method refresh

refresh: () => void;

method registerChildCommand

registerChildCommand: (
    command: Command,
    options?: { priority?: PriorityString }
) => void;

• Registers a child command.

  Parameter options

  An object with configuration options.

  Parameter

  options.priority Priority of a command to register.

property first

readonly first: PendingAction;

• Returns the first action from the list or null if the list is empty

  Returns

  The pending action object.

property hasAny

hasAny: boolean;

• Defines whether there is any registered pending action.

  Modifiers

  • @readonly

property pluginName

static readonly pluginName: string;

method [Symbol.iterator]

[Symbol.iterator]: () => Iterator<PendingAction>;

• Iterable interface.

method add

add: (message: string) => PendingAction;

• Adds an action to the list of pending actions.

  This method returns an action object with an observable message property. The action object can be later used in the method. It also allows you to change the message.

  Parameter message

  The action message.

  Returns

  An observable object that represents a pending action.

method init

init: () => void;

method remove

remove: (action: PendingAction) => void;

• Removes an action from the list of pending actions.

  Parameter action

  An action object.

constructor

constructor(editor: Editor);

property editor

readonly editor: Editor;

• The editor instance.

  Note that most editors implement the property. However, editors with an external UI (i.e. Bootstrap-based) or a headless editor may not have this property or throw an error when accessing it.

  Because of above, to make plugins more universal, it is recommended to split features into: - The "editing" part that uses the class without ui property. - The "UI" part that uses the class and accesses ui property.

property isContextPlugin

static readonly isContextPlugin: boolean;

property isEnabled

isEnabled: boolean;

• Flag indicating whether a plugin is enabled or disabled. A disabled plugin will not transform text.

  Plugin can be simply disabled like that:

  // Disable the plugin so that no toolbars are visible.
  editor.plugins.get( 'TextTransformation' ).isEnabled = false;

  You can also use method.

  Modifiers

  • @readonly

method clearForceDisabled

clearForceDisabled: (id: string) => void;

• Clears forced disable previously set through . See .

  Parameter id

  Unique identifier, equal to the one passed in call.

method destroy

destroy: () => void;

method forceDisabled

forceDisabled: (id: string) => void;

• Disables the plugin.

  Plugin may be disabled by multiple features or algorithms (at once). When disabling a plugin, unique id should be passed (e.g. feature name). The same identifier should be used when the plugin. The plugin becomes enabled only after all features .

  Disabling and enabling a plugin:

  plugin.isEnabled; // -> true
  plugin.forceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> false
  plugin.clearForceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> true

  Plugin disabled by multiple features:

  plugin.forceDisabled( 'MyFeature' );
  plugin.forceDisabled( 'OtherFeature' );
  plugin.clearForceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> false
  plugin.clearForceDisabled( 'OtherFeature' );
  plugin.isEnabled; // -> true

  Multiple disabling with the same identifier is redundant:

  plugin.forceDisabled( 'MyFeature' );
  plugin.forceDisabled( 'MyFeature' );
  plugin.clearForceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> true

  **Note:** some plugins or algorithms may have more complex logic when it comes to enabling or disabling certain plugins, so the plugin might be still disabled after was used.

  Parameter id

  Unique identifier for disabling. Use the same id when the plugin.

constructor

constructor(
    context: {},
    availablePlugins?: Iterable<PluginConstructor<TContext>>,
    contextPlugins?: Iterable<PluginEntry<TContext>>
);

• Creates an instance of the plugin collection class. Allows loading and initializing plugins and their dependencies. Allows providing a list of already loaded plugins. These plugins will not be destroyed along with this collection.

  Parameter availablePlugins

  Plugins (constructors) which the collection will be able to use when is used with the plugin names (strings, instead of constructors). Usually, the editor will pass its built-in plugins to the collection so they can later be used in config.plugins or config.removePlugins by names.

  Parameter contextPlugins

  A list of already initialized plugins represented by a [ PluginConstructor, pluginInstance ] pair.

method [Symbol.iterator]

[Symbol.iterator]: () => IterableIterator<PluginEntry<TContext>>;

• Iterable interface.

  Returns [ PluginConstructor, pluginInstance ] pairs.

method destroy

destroy: () => Promise<unknown>;

• Destroys all loaded plugins.

method get

get: {
    <TConstructor extends PluginClassConstructor<TContext>>(
        key: TConstructor
    ): InstanceType<TConstructor>;
    <TName extends string>(key: TName): PluginInterface;
};

method has

has: (key: PluginConstructor<TContext> | string) => boolean;

• Checks if a plugin is loaded.

  // Check if the 'Clipboard' plugin was loaded.
  if ( editor.plugins.has( 'ClipboardPipeline' ) ) {
  	// Now use the clipboard plugin instance:
  	const clipboard = editor.plugins.get( 'ClipboardPipeline' );
  
  	// ...
  }

  Parameter key

  The plugin constructor or .

method init

init: (
    plugins: ReadonlyArray<PluginConstructor<TContext> | string>,
    pluginsToRemove?: ReadonlyArray<PluginConstructor<TContext> | string>,
    pluginsSubstitutions?: ReadonlyArray<PluginConstructor<TContext>>
) => Promise<LoadedPlugins>;

• Initializes a set of plugins and adds them to the collection.

  Parameter plugins

  An array of or .

  Parameter pluginsToRemove

  Names of the plugins or plugin constructors that should not be loaded (despite being specified in the plugins array).

  Parameter pluginsSubstitutions

  An array of that will be used to replace plugins of the same names that were passed in plugins or that are in their dependency tree. A useful option for replacing built-in plugins while creating tests (for mocking their APIs). Plugins that will be replaced must follow these rules: * The new plugin must be a class. * The new plugin must be named. * Both plugins must not depend on other plugins.

  Returns

  A promise which gets resolved once all plugins are loaded and available in the collection.

index signature

[name: string]: Command;

method getData

getData: (options?: Record<string, unknown>) => string;

• Gets the data from the editor.

  editor.getData(); // -> '<p>This is editor!</p>'

  If your editor implementation uses multiple roots, you should pass root name as one of the options:

  editor.getData( { rootName: 'header' } ); // -> '<p>Content for header part.</p>'

  By default, the editor outputs HTML. This can be controlled by injecting a different data processor. See the guide for more details.

  A warning is logged when you try to retrieve data for a detached root, as most probably this is a mistake. A detached root should be treated like it is removed, and you should not save its data. Note, that the detached root data is always an empty string.

  Parameter options

  Additional configuration for the retrieved data. Editor features may introduce more configuration options that can be set through this parameter.

  Parameter

  options.rootName Root name. Default to 'main'.

  Parameter

  options.trim Whether returned data should be trimmed. This option is set to 'empty' by default, which means that whenever editor content is considered empty, an empty string is returned. To turn off trimming use 'none'. In such cases exact content will be returned (for example '<p>&nbsp;</p>' for an empty editor).

  Returns

  Output data.

method setData

setData: (data: string | Record<string, string>) => void;

• Sets the data in the editor.

  editor.setData( '<p>This is editor!</p>' );

  If your editor implementation uses multiple roots, you should pass an object with keys corresponding to the editor root names and values equal to the data that should be set in each root:

  editor.setData( {
      header: '<p>Content for header part.</p>',
      content: '<p>Content for main part.</p>',
      footer: '<p>Content for footer part.</p>'
  } );

  By default the editor accepts HTML. This can be controlled by injecting a different data processor. See the guide for more details.

  Parameter data

  Input data.

property context

context?: Context;

property extraPlugins

extraPlugins?: Array<PluginConstructor<Editor>>;

• The list of additional plugins to load along those already available in the . It extends the configuration.

  function MyPlugin( editor ) {
  	// ...
  }
  
  const config = {
  	extraPlugins: [ MyPlugin ]
  };

  **Note:** This configuration works only for simple plugins which utilize the and have no dependencies. To extend a build with complex features, create a .

  **Note:** Make sure you include the new features in you toolbar configuration. Learn more about the .

property initialData

initialData?: string | Record<string, string>;

• The initial editor data to be used instead of the provided element's HTML content.

  ClassicEditor
  	.create( document.querySelector( '#editor' ), {
  		initialData: '<h2>Initial data</h2><p>Foo bar.</p>'
  	} )
  	.then( ... )
  	.catch( ... );

  By default, the editor is initialized with the content of the element on which this editor is initialized. This configuration option lets you override this behavior and pass different initial data. It is especially useful if it is difficult for your integration to put the data inside the HTML element.

  If your editor implementation uses multiple roots, you should pass an object with keys corresponding to the editor roots names and values equal to the data that should be set in each root:

  MultiRootEditor.create(
  	// Roots for the editor:
  	{
  		header: document.querySelector( '#header' ),
  		content: document.querySelector( '#content' ),
  		leftSide: document.querySelector( '#left-side' ),
  		rightSide: document.querySelector( '#right-side' )
  	},
  	// Config:
  	{
  		initialData: {
  			header: '<p>Content for header part.</p>',
  			content: '<p>Content for main part.</p>',
  			leftSide: '<p>Content for left-side box.</p>',
  			rightSide: '<p>Content for right-side box.</p>'
  		}
  	}
  )
  .then( ... )
  .catch( ... );

  See also documentation for the editor implementation which you use.

  **Note:** If initial data is passed to Editor.create() in the first parameter (instead of a DOM element), and, at the same time, config.initialData is set, an error will be thrown as those two options exclude themselves.

  If config.initialData is not set when the editor is initialized, the data received in Editor.create() call will be used to set config.initialData. As a result, initialData is always set in the editor's config and plugins can read and/or modify it during initialization.

property language

language?: string | LanguageConfig;

• The language of the editor UI and its content.

  Note: You do not have to specify this option if your build is optimized for one UI language or if it is the default language (English is the default language for CDN builds), unless you want to change the language of your content.

  Simple usage (change the language of the UI and the content):

  ClassicEditor
  	.create( document.querySelector( '#editor' ), {
  		// The UI of the editor as well as its content will be in German.
  		language: 'de'
  	} )
  	.then( editor => {
  		console.log( editor );
  	} )
  	.catch( error => {
  		console.error( error );
  	} );

  Use different languages for the UI and the content using the syntax:

  ClassicEditor
  	.create( document.querySelector( '#editor' ), {
  		language: {
  			// The UI will be in English.
  			ui: 'en',
  
  			// But the content will be edited in Arabic.
  			content: 'ar'
  		}
  	} )
  	.then( editor => {
  		console.log( editor );
  	} )
  	.catch( error => {
  		console.error( error );
  	} );

  The language of the content has an impact on the editing experience, for instance it affects screen readers and spell checkers. It is also particularly useful for typing in certain languages (e.g. right–to–left ones) because it changes the default alignment of the text.

  The language codes are defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.

  You need to add the corresponding translation file for the new UI language to work. Translation files are available on CDN for predefined builds:

  `<script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/lang/[lang].js"></script>`

  But you can add them manually by coping from the node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/[lang].js'.

  Check the guide for more information about the localization options and translation process.

property licenseKey

licenseKey?: string;

• The license key for the CKEditor 5 commercial license and the premium features.

  If you do not have a key yet, please [contact us](https://ckeditor.com/contact/) or [order a trial](https://orders.ckeditor.com/trial/premium-features).

property placeholder

placeholder?: string | Record<string, string>;

• Specifies the text displayed in the editor when there is no content (editor is empty). It is intended to help users locate the editor in the application (form) and prompt them to input the content. Work similarly as to the native DOM [placeholder attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#The_placeholder_attribute) used by inputs.

  ClassicEditor
  	.create( document.querySelector( '#editor' ), {
  		placeholder: 'Type some text...'
  	} )
  	.then( ... )
  	.catch( ... );

  If your editor implementation uses multiple roots, you should pass an object with keys corresponding to the editor roots names and values equal to the placeholder that should be set in each root:

  MultiRootEditor.create(
  	// Roots for the editor:
  	{
  		header: document.querySelector( '#header' ),
  		content: document.querySelector( '#content' ),
  		leftSide: document.querySelector( '#left-side' ),
  		rightSide: document.querySelector( '#right-side' )
  	},
  	// Config:
  	{
  		placeholder: {
  			header: 'Type header...',
  			content: 'Type content...',
  			leftSide: 'Type left-side...',
  			rightSide: 'Type right-side...'
  		}
  	}
  )
  .then( ... )
  .catch( ... );

  The placeholder text is displayed as a pseudo–element of an empty paragraph in the editor content. The paragraph has the .ck-placeholder CSS class and the data-placeholder attribute.

  <p data-placeholder="Type some text..." class="ck-placeholder">
  	::before
  </p>

  **Note**: Placeholder text can also be set using the placeholder attribute if a <textarea> is passed to the create() method, e.g. .

  **Note**: This configuration has precedence over the value of the placeholder attribute of a <textarea> element passed to the create() method.

  See the guide for more information and live examples.

property plugins

plugins?: Array<PluginConstructor<Editor> | string>;

• The list of plugins to load.

  If you use an you can define the list of plugins to load using the names of plugins that are available:

  const config = {
  	plugins: [ 'Bold', 'Italic', 'Typing', 'Enter', ... ]
  };

  You can check the list of plugins available in a build using this snippet:

  ClassicEditor.builtinPlugins.map( plugin => plugin.pluginName );

  If you use an editor creator directly (imported from a package like @ckeditor/ckeditor5-editor-classic) or you want to load additional plugins which were not included in a build you use, then you need to specify the plugins using their constructors:

  // A preset of plugins is a plugin as well.
  import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
  // The bold plugin.
  import Bold from '@ckeditor/ckeditor5-editor-basic-styles/src/bold';
  
  const config = {
  	plugins: [ Essentials, Bold ]
  };

  **Note:** To load additional plugins, you should use the configuration. To narrow the list of loaded plugins, use the configuration.

property removePlugins

removePlugins?: Array<PluginConstructor<Editor> | string>;

• The list of plugins which should not be loaded despite being available in an .

  const config = {
  	removePlugins: [ 'Bold', 'Italic' ]
  };

  **Note:** Be careful when removing plugins using config.removePlugins from CKEditor builds. If removed plugins were providing toolbar buttons, the default toolbar configuration included in a build will become invalid. In such case you need to provide the updated .

property substitutePlugins

substitutePlugins?: Array<PluginConstructor<Editor>>;

property toolbar

toolbar?: ToolbarConfig;

• The editor toolbar configuration.

  Simple format (specifies only toolbar items):

  const config = {
  	toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
  };

  Extended format:

  const config = {
  	toolbar: {
  		items: [ 'bold', 'italic', '|', 'undo', 'redo', '-', 'numberedList', 'bulletedList' ],
  
  		shouldNotGroupWhenFull: true
  	}
  };

  Options which can be set using the extended format:

  * **toolbar.items** – An array of toolbar item names. The components (buttons, dropdowns, etc.) which can be used as toolbar items are defined in editor.ui.componentFactory and can be listed using the following snippet:

  ```ts Array.from( editor.ui.componentFactory.names() ); ```

  You can also use '|' to create a separator between groups of items:

  ``` toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ] ```

  or '-' to make a line break and render items in multiple lines:

  ``` toolbar: [ 'bold', 'italic', '-', 'undo', 'redo' ] ```

  Line break will work only in the extended format when shouldNotGroupWhenFull option is set to true.

  **Note**: To save space in your toolbar, you can group several items into a dropdown:

  ``` toolbar: [ { label: 'Basic styles', icon: 'text', items: [ 'bold', 'italic', ... ] }, '|', 'undo', 'redo' ] ```

  The code above will create a "Basic styles" dropdown with a "text" icon containing the "bold" and "italic" buttons. You can customize the look of the dropdown by setting the withText, icon, and tooltip properties:

  * **Displaying a label**

  For instance, to hide the icon and to display the label only, you can use the following configuration:

  ```ts { label: 'Basic styles', // Show the textual label of the drop-down. Note that the "icon" property is not configured. withText: true, items: [ 'bold', 'italic', ... ] } ```

  * **Selecting an icon**

  You can use one of the common icons provided by the editor ('bold', 'plus', 'text', 'importExport', 'alignLeft', 'paragraph', 'threeVerticalDots', 'dragIndicator', 'pilcrow'):

  ```ts { label: '...', // A "plus" sign icon works best for content insertion tools. icon: 'plus', items: [ ... ] } ```

  If no icon is specified, 'threeVerticalDots' will be used as a default:

  ```ts // No icon specified, using a default one. { label: 'Default icon', items: [ ... ] } ```

  If icon: false is configured, no icon will be displayed at all and the text label will show up instead:

  ```ts // This drop-down has no icon. The text label will be displayed instead. { label: 'No icon', icon: false, items: [ ... ] } ```

  You can also set a custom icon for the drop-down by passing an SVG string:

  ```ts { label: '...', // If you want your icon to change the color dynamically (e.g. when the dropdown opens), avoid fill="..." // and stroke="..." styling attributes. Use solid shapes and avoid paths with strokes. icon: '...', items: [ ... ] } ```

  * **Customizing the tooltip**

  By default, the tooltip of the button shares its text with the label. You can customize it to better describe your dropdown using the tooltip property ():

  ```ts { label: 'Drop-down label', tooltip: 'Custom tooltip of the drop-down', icon: '...', items: [ ... ] } ```

  * **toolbar.viewportTopOffset (deprecated)** – The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar. Useful when a page with which the editor is being integrated has some other sticky or fixed elements (e.g. the top menu). Thanks to setting the toolbar offset the toolbar will not be positioned underneath or above the page's UI.

  **This property has been deprecated and will be removed in the future versions of CKEditor. Please use {@link module:core/editor/editorconfig~EditorConfig#ui EditorConfig#ui.viewportOffset} instead.**

  * **toolbar.shouldNotGroupWhenFull** – When set to true, the toolbar will stop grouping items and let them wrap to the next line if there is not enough space to display them in a single row.

property ui

ui?: UiConfig;

• The editor UI configuration.

  ClassicEditor
  	.create( document.querySelector( '#editor' ), {
  		ui: { ... }
  	} )
  	.then( ... )
  	.catch( ... );

  Options which can be set using the UI configuration:

  * **ui.viewportOffset** – The offset (in pixels) of the viewport from every direction. It is used when positioning a sticky toolbar or other absolutely positioned UI elements. Useful when a page with which the editor is being integrated has some other sticky or fixed elements (e.g. the top menu). Thanks to setting the UI viewport offset, the toolbar and other contextual balloons will not be positioned underneath or above the page's UI.

  ```ts ui: { viewportOffset: { top: 10, right: 10, bottom: 10, left: 10 } } ```

  **Note:** If you want to modify the viewport offset in runtime (after the editor was created), you can do that by overriding .

  * **ui.poweredBy** – The configuration of the project logo displayed over the editor's editing area in open-source integrations. It allows customizing the position of the logo to minimize the risk of collision with the editor content and UI.

  The following configuration properties are supported:

  * **position** – The position of the project's logo (default: 'border'). * When 'inside', the logo will be displayed within the boundaries of the editing area. * When 'border', the logo will be displayed over the bottom border of the editing area.

  * **side** ('left' or 'right', default: 'right') – The side of the editing area where the logo will be displayed.

  **Note**: If is set to an RTL (right-to-left) language, the side switches to 'left' by default.

  * **label** (default: 'Powered by') – The label displayed next to the project's logo.

  **Note**: Set the value to null to display the logo without any text.

  * **verticalOffset** (default: 5) – The vertical distance the logo can be moved away from its default position.

  **Note**: If position is 'border', the offset is measured from the (vertical) center of the logo.

  * **horizontalOffset** (default: 5) – The horizontal distance between the side of the editing root and the nearest side of the logo.

  ```ts ui: { poweredBy: { position: 'border', side: 'left', verticalOffset: 2, horizontalOffset: 30 } }

property updateSourceElementOnDestroy

updateSourceElementOnDestroy?: boolean;

• Enables updating the source element after the editor is destroyed.

  Enabling this option might have some security implications, as the editor doesn't have control over all data in the output.

  Be careful, especially while using the , , or features.

property sourceElement

sourceElement: HTMLElement | undefined;

• The element on which the editor has been initialized.

  Modifiers

  • @readonly

method updateSourceElement

updateSourceElement: (data?: string) => void;

• Updates the 's content with the data if the configuration option is set to true.

  Parameter data

  Data that the should be updated with.

property content

content?: string;

• Allows to use a different language of the editor content.

  The language codes are defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.

property ui

ui?: string;

• Allows to use a different language for the editor UI.

  The language codes are defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.

property message

message: string;