CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

EditorConfig (core/editor)

@ckeditor/ckeditor5-core/src/editor/editorconfig

interface
See source

CKEditor configuration options.

An object defining the editor configuration can be passed when initializing the editor:

EditorClass
	.create( {
		toolbar: [ 'bold', 'italic' ],
		image: {
			styles: [
				...
			]
		}
	} )
	.then( ... )
	.catch( ... );

Check the Configuration guide for more information about setting configuration options.

Filtering

Properties

  • alignment : AlignmentConfig | undefined

    See source

    The configuration of the alignment feature.

    Read more in AlignmentConfig.

  • autosave : AutosaveConfig | undefined

    See source

    The configuration of the autosave feature.

    Read more in AutosaveConfig.

  • balloonToolbar : ToolbarConfig | undefined

    See source

    Contextual toolbar configuration. Used by the BalloonToolbar feature.

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

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

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

    Read also about configuring the main editor toolbar in toolbar.

    Configuring items grouping

    You can prevent automatic items grouping by setting the shouldNotGroupWhenFull option:

    const config = {
	balloonToolbar: {
		items: [ 'bold', 'italic', 'undo', 'redo' ],
		shouldNotGroupWhenFull: true
	},
};

  • blockToolbar : ToolbarConfig | undefined

    See source

    The block toolbar configuration. Used by the BlockToolbar feature.

    const config = {
	blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'bulletedList', 'numberedList' ]
};

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

    const config = {
	blockToolbar: [ 'paragraph', 'heading1', 'heading2', '|', 'bulletedList', 'numberedList' ]
};
    Configuring items grouping

    You can prevent automatic items grouping by setting the shouldNotGroupWhenFull option:

    const config = {
	blockToolbar: {
		items: [ 'paragraph', 'heading1', 'heading2', '|', 'bulletedList', 'numberedList' ],
		shouldNotGroupWhenFull: true
	},
};

    Read more about configuring the main editor toolbar in toolbar.

  • ckbox : CKBoxConfig | undefined

    See source

    The configuration of the CKBox feature.

    Read more in CKBoxConfig.

  • ckfinder : CKFinderConfig | undefined

    See source

    The configuration of the CKFinder feature.

    Read more in CKFinderConfig.

  • cloudServices : CloudServicesConfig | undefined

    See source

    The configuration of CKEditor Cloud Services. Introduced by the CloudServices plugin.

    Read more in CloudServicesConfig.

  • codeBlock : CodeBlockConfig | undefined

    See source

    The configuration of the CodeBlock feature.

    Read more in CodeBlockConfig.

  • collaboration : RealTimeCollaborationConfig | undefined

    The configuration of the real time collaboration feature.

    Read more in RealTimeCollaborationConfig.

    See all editor options.

  • comments : CommentsConfig | undefined

    The configuration of the comments feature. Introduced by the Comments feature.

    Read more in CommentsConfig.

    ClassicEditor
	.create( {
		comments: ... // Locale editor configuration.
	} )
	.then( ... )
	.catch( ... );

    See all editor options.

  • commentsOnly : boolean | undefined

    Enables comments-only mode when the editor initializes.

    ClassicEditor
	.create( {
		commentsOnly: true
	} )
	.then( ... )
	.catch( ... );

  • context : Context | undefined

    See source

  • documentOutline : DocumentOutlineConfig | undefined

    The configuration of the DocumentOutline feature.

    Read more in DocumentOutlineConfig.

  • exportPdf : ExportPdfConfig | undefined

    The configuration of the export to PDF feature.

    Read more in ExportPdfConfig.

  • exportWord : ExportWordConfig | undefined

    The configuration of the export to Word feature.

    Read more in ExportWordConfig.

  • extraPlugins : Array<PluginConstructor<Editor>> | undefined

    See source

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

    function MyPlugin( editor ) {
	// ...
}

const config = {
	extraPlugins: [ MyPlugin ]
};

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

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

  • fontBackgroundColor : FontColorConfig | undefined

    See source

    The configuration of the font background color feature. It is introduced by the FontBackgroundColorEditing feature.

    Read more in FontColorConfig.

  • fontColor : FontColorConfig | undefined

    See source

    The configuration of the font color feature. It is introduced by the FontColorEditing feature.

    Read more in FontColorConfig.

  • fontFamily : FontFamilyConfig | undefined

    See source

    The configuration of the font family feature. It is introduced by the FontFamilyEditing feature.

    Read more in FontFamilyConfig.

  • fontSize : FontSizeConfig | undefined

    See source

    The configuration of the font size feature. It is introduced by the FontSizeEditing feature.

    Read more in FontSizeConfig.

  • heading : HeadingConfig | undefined

    See source

    The configuration of the heading feature. Introduced by the HeadingEditing feature.

    Read more in HeadingConfig.

  • highlight : HighlightConfig | undefined

    See source

    The configuration of the Highlight feature.

    Read more in HighlightConfig.

  • htmlEmbed : HtmlEmbedConfig | undefined

    See source

    The configuration of the HTML embed feature. Introduced by the HtmlEmbedEditing feature.

    Read more in all editor options.

  • htmlSupport : GeneralHtmlSupportConfig | undefined

    See source

    The configuration of the General HTML Support feature. Introduced by the GeneralHtmlSupport feature.

    Read more in GeneralHtmlSupportConfig.

  • image : ImageConfig | undefined

    See source

    The configuration of the image features. Used by the image features in the @ckeditor/ckeditor5-image package.

    Read more in ImageConfig.

  • importWord : ImportWordConfig | undefined

    The configuration of the import from Word feature.

    Read more in ImportWordConfig.

  • indentBlock : IndentBlockConfig | undefined

    See source

    The configuration of the block indentation feature.

    Read more in IndentBlockConfig.

  • initialData : string | Record<string, string> | undefined

    See source

    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 Editor.create() 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.

  • language : string | LanguageConfig | undefined

    See source

    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 configuration 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 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 UI language guide for more information about the localization options and translation process.

  • lazyRoots : Array<string> | undefined

    See source

    A list of names of all the roots that exist in the document but are not initially loaded by the editor.

    These roots can be loaded at any time after the editor has been initialized, using MultiRootEditor#lazyRoot().

    This is useful for handling big documents that contain hundreds of roots, or contain very large roots, which may have impact editor performance if loaded all at once.

  • licenseKey : string | undefined

    See source

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

    If you do not have a key yet, please contact us or order a trial.

  • link : LinkConfig | undefined

    See source

    The configuration of the Link feature.

    Read more in LinkConfig.

  • list : ListConfig | undefined

    See source

    The configuration of the List feature and the DocumentList feature.

    Read more in ListConfig.

  • locale : LocaleConfig | undefined

    The locale configuration of the editor.

  • mediaEmbed : MediaEmbedConfig | undefined

    See source

    The configuration of the MediaEmbed feature.

    Read more in MediaEmbedConfig.

  • mention : MentionConfig | undefined

    See source

    The configuration of the Mention feature.

    Read more in MentionConfig.

  • minimap : MinimapConfig | undefined

    See source

    The configuration of the minimap feature. Introduced by the Minimap feature.

    Read more in MinimapConfig.

  • pagination : PaginationConfig | undefined

    The configuration of the pagination feature. It is used by the pagination feature from the @ckeditor/ckeditor5-pagination package.

    Read more in PaginationConfig.

  • placeholder : string | Record<string, string> | undefined

    See source

    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 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. ClassicEditor.create().

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

    See the "Editor placeholder" guide for more information and live examples.

  • plugins : Array<string | PluginConstructor<Editor>> | undefined

    See source

    The list of plugins to load.

    If you use an editor build 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 extraPlugins configuration. To narrow the list of loaded plugins, use the removePlugins configuration.

  • presenceList : PresenceListConfig | undefined

  • removePlugins : Array<string | PluginConstructor<Editor>> | undefined

    See source

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

    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 toolbar configuration.

  • restrictedEditing : RestrictedEditingConfig | undefined

    See source

    The configuration of the restricted editing mode feature. Introduced by the RestrictedEditingMode feature.

    Read more in RestrictedEditingConfig.

  • revisionHistory : RevisionHistoryConfig | undefined

    The configuration of the revision history feature. Introduced by the RevisionHistory feature.

  • rootsAttributes : Record<string, RootAttributes> | undefined

    See source

    Initial roots attributes for the document roots.

    Note: This configuration option is supported only by the multi-root editor type.

    Note: You must provide full set of attributes for each root. If an attribute is not set on a root, set the value to null. Only provided attribute keys will be returned by getRootsAttributes.

    Roots attributes hold additional data related to the document roots, in addition to the regular document data (which usually is HTML). In roots attributes, for each root, you can store arbitrary key-value pairs with attributes connected with that root. Use it to store any custom data that is specific to your integration or custom features.

    Currently, roots attributes are not used only by any official plugins. This is a mechanism that is prepared for custom features and non-standard integrations. If you do not provide any custom feature that would use root attributes, you do not need to handle (save and load) this property.

    MultiRootEditor.create(
	// Roots for the editor:
	{
		uid1: document.querySelector( '#uid1' ),
		uid2: document.querySelector( '#uid2' ),
		uid3: document.querySelector( '#uid3' ),
		uid4: document.querySelector( '#uid4' )
	},
	// Config:
	{
		rootsAttributes: {
			uid1: { order: 20, isLocked: false }, // Third, unlocked.
			uid2: { order: 10, isLocked: true }, // Second, locked.
			uid3: { order: 30, isLocked: true }, // Fourth, locked.
			uid4: { order: 0, isLocked: false } // First, unlocked.
		}
	}
)
.then( ... )
.catch( ... );

    Note, that the above code snippet is only an example. You need to implement your own features that will use these attributes.

    Roots attributes can be changed the same way as attributes set on other model nodes:

    editor.model.change( writer => {
	const root = editor.model.getRoot( 'uid3' );

	writer.setAttribute( 'order', 40, root );
} );

    You can react to root attributes changes by listening to document change:data event:

    editor.model.document.on( 'change:data', () => {
	const changedRoots = editor.model.document.differ.getChangedRoots();

	for ( const change of changedRoots ) {
		if ( change.attributes ) {
			const root = editor.model.getRoot( change.name );

			// ...
		}
	}
} );

  • sidebar : SidebarConfig | undefined

    The configuration of the sidebar feature. Introduced by the Sidebar feature.

  • simpleUpload : SimpleUploadConfig | undefined

    See source

    The configuration of the simple upload adapter.

    Read more in SimpleUploadConfig.

  • slashCommand : SlashCommandEditorConfig | undefined

    The configuration of the SlashCommand feature.

    Read more in SlashCommandEditorConfig.

  • specialCharacters : SpecialCharactersConfig | undefined

    See source

    The configuration of the SpecialCharacters feature.

    Read more in SpecialCharactersConfig.

  • style : StyleConfig | undefined

    See source

    The configuration of the Style feature.

    Read more in StyleConfig.

  • substitutePlugins : Array<PluginConstructor<Editor>> | undefined

    See source

  • table : TableConfig | undefined

    See source

    The configuration of the Table feature.

    Read more in TableConfig.

  • template : TemplateConfig | undefined

    The configuration of the Template feature.

    Read more in TemplateConfig.

  • title : TitleConfig | undefined

    See source

    The configuration of the title feature.

    Read more in TitleConfig.

  • toolbar : ToolbarConfig | undefined

    See source

    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:

      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'`):

	```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: '<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg">...</svg>',
		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 (learn more):

	```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 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.

  • trackChanges : TrackChangesConfig | undefined

    The configuration of the TrackChanges feature.

    Read more in TrackChangesConfig.

  • trackChangesData : Object | undefined

    The configuration of the track changes data feature.

  • typing : TypingConfig | undefined

    See source

    The configuration of the typing features. Used by the features from the @ckeditor/ckeditor5-typing package.

    Read more in TypingConfig.

  • ui : UiConfig | undefined

    See source

    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.

      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 editor.ui.viewportOffset.

    • 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 config.language 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.

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

  • updateSourceElementOnDestroy : boolean | undefined

    See source

    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 Markdown, General HTML Support, or HTML embed features.

  • users : Object | undefined

    The users plugin configuration.

  • wordCount : WordCountConfig | undefined

    See source

    The configuration of the word count feature. It is introduced by the WordCount feature.

    Read more in WordCountConfig.

  • internal

    _watchdogInitialData : EditorData | undefined

    See source

    The temporary property that is used for passing data to the plugin which restores the editor state.