Editor placeholder
You can prompt the user to input content by displaying a configurable placeholder text when the editor is empty. This works similarly to the native DOM placeholder
attribute used by inputs. Not to be confused with the content placeholders offered by the merge fields feature.
# Demo
See the demo of the placeholder feature:
This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.
# Installation
The editor placeholder feature does not require a separate plugin installation. It does, however, require configuring the editor before use. There are two different ways of configuring the editor placeholder text:
# Using the placeholder
attribute of a textarea
Set the placeholder
attribute on a <textarea>
element passed to the Editor.create()
method (for instance ClassicEditor.create()
) to configure the placeholder:
<textarea id="editor" placeholder="Type the content here!"></textarea>
import { ClassicEditor, Essentials } from 'ckeditor5';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Essentials, /* ... */ ],
} )
.then( editor => {
console.log( editor );
} )
.catch( error => {
console.error( error );
} );
# Using the editor configuration
You can use the editor.config.placeholder
configuration option:
- when no element was passed into
Editor.create()
method, - when the element passed into
Editor.create()
was not a<textarea>
(for instance, a<div>
element), - to override the
placeholder
text of a<textarea>
, if one was passed intoEditor.create()
but the placeholder text should be different.
import { ClassicEditor, Essentials } from 'ckeditor5';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Essentials, /* ... */ ],
placeholder: 'Type the content here!'
} )
.then( editor => {
console.log( editor );
} )
.catch( error => {
console.error( error );
} );
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( editor => {
console.log( editor );
} )
.catch( error => {
console.error( error );
} );
# Styling the placeholder
The editor placeholder text is displayed using a CSS pseudo–element (::before
) related to the first empty element in the editor content (usually a paragraph). You can use the following snippet to change the appearance of the placeholder:
.ck.ck-editor__editable > .ck-placeholder::before {
color: #d21714;
font-family: Georgia;
}
Note: The .ck-placeholder
class is also used to display placeholders in other places, for instance, image captions. Make sure your custom styles apply to the right subset of placeholders.
# Changing the placeholder
The editor placeholder could be updated at runtime by changing the placeholder
property in the editing root.
editor.editing.view.document.getRoot( 'main' ).placeholder = 'new placeholder';
# Contribute
The source code of the feature is available on GitHub at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.