EditorConfig (core/editor)
@ckeditor/ckeditor5-core/src/editor/editorconfig
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
-
The configuration of the alignment feature.
Read more in
AlignmentConfig
. -
The configuration of the autosave feature.
Read more in
AutosaveConfig
. -
balloonToolbar : Array.<String> | Object
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 : Array.<String> | Object
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' ] };
Read more about configuring the main editor toolbar in
toolbar
. -
The configuration of the CKFinder feature.
Read more in
CKFinderConfig
. -
The configuration of CKEditor Cloud Services. Introduced by the
CloudServices
plugin.Read more in
CloudServicesConfig
. -
The configuration of the
CodeBlock
feature.Read more in
CodeBlockConfig
. -
extraPlugins : Array.<Function>
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 toolbar setup.
-
The configuration of the font background color feature. It is introduced by the
FontBackgroundColorEditing
feature.Read more in
FontBackgroundColorConfig
. -
The configuration of the font color feature. It is introduced by the
FontColorEditing
feature.Read more in
FontColorConfig
. -
The configuration of the font family feature. It is introduced by the
FontFamilyEditing
feature.Read more in
FontFamilyConfig
. -
The configuration of the font size feature. It is introduced by the
FontSizeEditing
feature.Read more in
FontSizeConfig
. -
The configuration of the heading feature. Introduced by the
HeadingEditing
feature.Read more in
HeadingConfig
. -
The configuration of the
Highlight
feature.Read more in
HighlightConfig
. -
The configuration of the image features. Used by the image features in the
@ckeditor/ckeditor5-image
package.Read more in
ImageConfig
. -
The configuration of the block indentation feature.
Read more in
IndentBlockConfig
. -
initialData : 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. See Editor.create().
This configuration option lets you override initial data if an element is passed to
Editor.create()
. It is especially useful if it is difficult for your integration to put the data inside the HTML element.Note: If initial data is passed to
Editor.create()
as a parameter and, at the same time, via this configuration option, an error will be thrown as those two options exclude themselves. -
language : String | Object
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 object 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.
-
The configuration of the
Link
feature.Read more in
LinkConfig
. -
The configuration of the
MediaEmbed
feature.Read more in
MediaEmbedConfig
. -
The configuration of the
Mention
feature.Read more in
MentionConfig
. -
placeholder : 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 used by inputs.const config = { placeholder: 'Type some text...' };
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 thedata-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 thecreate()
method, e.g.ClassicEditor.create()
.Note: This configuration has precedence over the value of the
placeholder
attribute of a<textarea>
element passed to thecreate()
method.See the "Editor placeholder" guide for more information and live examples.
-
plugins : Array.<(String | Function)>
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 theremovePlugins
configuration. -
removePlugins : Array.<String>
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. -
The configuration of the restricted editing mode feature. Introduced by the
RestrictedEditingMode
feature.Read more in
RestrictedEditingModeConfig
. -
The configuration of the simple upload adapter.
Read more in
SimpleUploadConfig
. -
The configuration of the
Table
feature.Read more in
TableConfig
. -
The configuration of the title feature.
Read more in
TitleConfig
. -
toolbar : Array.<String> | Object
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' ], viewportTopOffset: 30, 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 ineditor.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' ]
toolbar.viewportTopOffset
– 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.toolbar.shouldNotGroupWhenFull
– When settrue
, the toolbar will stop grouping items that wrap to the next line when there is not enough space to display them in a single row.
-
The configuration of the typing features. Used by the features from the
@ckeditor/ckeditor5-typing
package.Read more in
TypingConfig
. -
The configuration of the word count feature. It is introduced by the
WordCount
feature.Read more in
WordCountConfig
.