Contribute to this guide

guideSpecial characters

The SpecialCharacters plugin provides a possibility to insert special characters into the rich-text editor. These would typically include characters and signs that serve a specific purpose, like mathematical operators, currency symbols, punctuation, graphic symbols (e.g. arrows or bullets). The feature may be used to provide fast access to a broader selection of Unicode letters typically not accessible from the keyboard, like umlauts or other diacritics. It also provides support for emojis.

# Demo

Use the editor below to see the special characters plugin in action.

Euro foreign exchange reference rates

As of February 10, 2020

All currencies quoted against the euro (€) as base currency.

  • Currency: US Dollar, symbol: $, spot: 1.0951
  • Currency: British Pound, symbol: £, spot: 0.8463
  • Currency: Indian Rupee, symbol: , spot: 78.1070
  • Currency: Japanese Yen, symbol: ¥, spot: 120.1800
  • Currency: Russian Ruble, symbol: , spot: 70.1120
  • Currency: Turkish Lira, symbol: , spot: 6.5897

# Configuration

By default, a few categories of special characters have been defined. You can easily customize the special characters available in your WYSIWYG editor installation by adding new categories, extending the existing ones or removing them altogether.

# Adding a new category

You can define a new special characters category using the SpecialCharacters#addItems() function.

For example, the following plugin adds the “Emoji” category to the special characters dropdown.

import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';

function SpecialCharactersEmoji( editor ) {
    editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [
        { title: 'smiley face', character: '😊' },
        { title: 'rocket', character: '🚀' },
        { title: 'wind blowing face', character: '🌬️' },
        { title: 'floppy disk', character: '💾' },
        { title: 'heart', character: '❤️' }
    ] );
}

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [
            SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersEmoji,

            // Other plugins...
        ],
        toolbar: [ 'specialCharacters', ... ],
    } )
    .then( ... )
    .catch( ... );

After adding the above plugin to the editor configuration, the new category will become available in the special characters dropdown.

The title of a special character must be unique across the entire special characters set.

Below you can see a demo based on the example shown above. Use the special characters icon in the editor toolbar and then select “Emoji” in the select dropdown in order to insert an emoji into the WYSIWYG editor.

Build your CKEditor 5 in a breeze. 🌬 Choose an editor type and customize plugins, toolbar and language in 5 simple steps. 😊

The new CKEditor 5 online builder is finally here! 🚀

# Adding characters to an existing category

By using the SpecialCharacters#addItems() function you can also add new special characters into an existing category.

import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';

function SpecialCharactersArrowsExtended( editor ) {
    editor.plugins.get( 'SpecialCharacters' ).addItems( 'Arrows', [
        { title: 'simple arrow left', character: '←' },
        { title: 'simple arrow up', character: '↑' },
        { title: 'simple arrow right', character: '→' },
        { title: 'simple arrow down', character: '↓' }
    ] );
}

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [
            SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersArrowsExtended,

            // Other plugins...
        ],
        toolbar: [ 'specialCharacters', ... ],
    } )
    .then( ... )
    .catch( ... );

The title of a special character must be unique across the entire special characters set.

Below, you can see a demo based on the example shown above. Use the special characters icon in the editor toolbar and then select “Arrows” in the select dropdown. You will see that the category now contains the additional arrow characters added in the configuration above.

Euro foreign exchange reference rates

As of February 10, 2020

All currencies quoted against the euro (€) as base currency.

  • Currency: US Dollar, symbol: $, spot: 1.0951, change:
  • Currency: British Pound, symbol: £, spot: 0.8463, change:
  • Currency: Indian Rupee, symbol: , spot: 78.1070, change:
  • Currency: Japanese Yen, symbol: ¥, spot: 120.1800, change:
  • Currency: Russian Ruble, symbol: , spot: 70.1120, change:
  • Currency: Turkish Lira, symbol: , spot: 6.5897, change:

# Removing categories

The special characters feature exposes each category as a separate plugin. While the SpecialCharactersEssentials plugin can be used to conveniently include all of them, you can customize the category list by adding individual plugins with particular categories.

By default, the @ckeditor/ckeditor5-special-characters package provides special characters grouped into the following categories:

For example, you can limit the categories to “Mathematical” and “Currency” only by picking the SpecialCharactersMathematical and SpecialCharactersCurrency plugins, like so:

import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
import SpecialCharactersCurrency from '@ckeditor/ckeditor5-special-characters/src/specialcharacterscurrency';
import SpecialCharactersMathematical from '@ckeditor/ckeditor5-special-characters/src/specialcharactersmathematical';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [
            SpecialCharacters, SpecialCharactersCurrency, SpecialCharactersMathematical,

            // Other plugins...
        ],
        toolbar: [ 'specialCharacters', ... ],
    } )
    .then( ... )
    .catch( ... );

Below, you can see a demo based on the example shown above. After clicking the special character icon in the editor toolbar you can see that it contains fewer categories compared to other editors on this page.

Euro foreign exchange reference rates

As of February 10, 2020

All currencies quoted against the euro (€) as base currency.

  • Currency: US Dollar, symbol: $, spot: 1.0951
  • Currency: British Pound, symbol: £, spot: 0.8463
  • Currency: Indian Rupee, symbol: , spot: 78.1070
  • Currency: Japanese Yen, symbol: ¥, spot: 120.1800
  • Currency: Russian Ruble, symbol: , spot: 70.1120
  • Currency: Turkish Lira, symbol: , spot: 6.5897

# Installation

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

npm install --save @ckeditor/ckeditor5-special-characters

And add it to your plugin list configuration:

// Core plugin that provides the API for the management of special characters and their categories.
import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
// A plugin that combines a basic set of special characters.
import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';

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

Read more about installing plugins.

# Common API

The SpecialCharacters plugin registers the UI button component ('specialCharacters').

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/tree/master/packages/ckeditor5-special-characters.