Contribute to this guideReport an issue

guideWord count

The WordCount feature provides a possibility to track the number of words and characters written in the editor.

# Demo

The Battle of Westerplatte was one of the first battles in Germany's invasion of Poland, marking the start of World War II in Europe. Beginning on 1 September 1939, German army, naval and air forces and Danzig police assaulted Poland's Military Transit Depot (Wojskowa Składnica Tranzytowa, or WST) on the Westerplatte peninsula in the harbor of the Free City of Danzig. The Poles held out for seven days and repelled 13 assaults that included dive-bomber attacks and naval shelling.

Westerplatte's defense served as an inspiration for the Polish Army and people in the face of German advances elsewhere, and is still regarded as a symbol of resistance in modern Poland.

<div id="editor">
    <p>Hello world.</p>
</div>
<div id="word-count">
</div>
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // Configuration details.
    } )
    .then( editor => {
        const wordCountPlugin = editor.plugins.get( 'WordCount' );
        const wordCountWrapper = document.getElementById( 'word-count' );

        wordCountWrapper.appendChild( wordCountPlugin.wordCountContainer );
    } )
    .catch( ... );

# Configuration options

There are two options which change the output container. If the displayWords is set to to false, then the section with word count is hidden. Similarly, when the displayCharacters is set to false it will hide the character counter.

# Update event

Word count feature emits an update event whenever there is a change in the model. This allows implementing customized behavior that reacts to word count updates.

Below you can find an example, where the background color of a square is changed according to the number of characters in the editor. There is also a progress bar which indicates how many words is in it (the maximal value of the progress bar is set to 100, however, you can write further and progress bar remain in the maximal state).

A black hole is a region of spacetime exhibiting gravitational acceleration so strong that nothing—no particles or even electromagnetic radiation such as light—can escape from it.[6] The theory of general relativity predicts that a sufficiently compact mass can deform spacetime to form a black hole.

Characters:
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // configuration details
    } )
    .then( editor => {
        const wordCountPlugin = editor.plugins.get( 'WordCount' );

        wordCountPlugin.on( 'update', ( evt, data ) => {
            // data is an object with "words" and "characters" field
            doSthWithNewWordsNumber( data.words );
            doSthWithNewCharactersNumber( data.characters );
        } );

    } )
    .catch( ... );

# Installation

To add this feature to your rich-text editor, install the @ckeditor/ckeditor5-word-count package:

npm install --save @ckeditor/ckeditor5-word-count

And add it to your plugin list configuration:

import WordCount from '@ckeditor/ckeditor5-word-count/src/wordcount';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ WordCount, ... ],
    } )
    .then( ... )
    .catch( ... );

Read more about installing plugins.

# Common API

The WordCount plugin provides:

  • wordCountContainer method. It returns a self-updating HTML element which is updated with the current number of words and characters in the editor. There is a possibility to remove “Words” or “Characters” counters with proper configuration of displayWords and displayCharacters,
  • update event which is fired whenever the plugins update the number of counted words and characters. There is a possibility to run own callback function with updated values. Please note that update event is throttled.

We recommend using the official CKEditor 5 inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

# Contribute

The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-word-count.