Special characters

The special characters feature lets you insert mathematical operators, currency symbols, punctuation, graphic symbols (such as arrows or bullets), or Unicode letters typically not accessible from the keyboard (such as umlauts or other diacritics). The feature also supports emojis.

# Demo

Use the special characters toolbar button in the editor below to open a configurable panel with a table of selectable special characters.

# 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, SpecialCharactersEssentials } from '@ckeditor/ckeditor5-special-characters';

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: '❤️' }
    ], { label: 'Emoticons' } );
}

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [
            SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersEmoji,
            // More 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.

Below you can see a demo based on the example shown above. Use the special characters toolbar button and then select “Emoticons” from the dropdown. This will let you insert an emoji into the content.

# Adding characters to an existing category

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

import { SpecialCharacters, SpecialCharactersEssentials } from '@ckeditor/ckeditor5-special-characters';

function SpecialCharactersExtended( editor ) {
    editor.plugins.get( 'SpecialCharacters' ).addItems( 'Mathematical', [
        { title: 'alpha', character: 'α' },
        { title: 'beta', character: 'β' },
        { title: 'gamma', character: 'γ' }
    ] );
}

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

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

Below you can see a demo based on the example shown above. Use the special characters toolbar button and then select “Mathematical” from the dropdown. You will see that the category now contains the additional Greek letters introduced by the configuration above.

# 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:

• SpecialCharactersArrows – Arrows special characters.
• SpecialCharactersCurrency – Currency special characters.
• SpecialCharactersLatin – Latin special characters.
• SpecialCharactersMathematical – Mathematical special characters.
• SpecialCharactersText – Text special characters.
• SpecialCharactersEssentials – Combines the plugins listed above.

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

import { SpecialCharacters, SpecialCharactersCurrency, SpecialCharactersMathematical } from '@ckeditor/ckeditor5-special-characters';

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

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

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

# Ordering categories

The order of categories in the UI is determined by the order in which they were registered. However, depending on the context in which you use the editor, you might want to change this order, to make it easier to access frequently used characters.

The categories order can be customized using the order array.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SpecialCharacters, SpecialCharactersEssentials, ... ],
        specialCharacters: {
            order: [
                'Text',
                'Latin',
                'Mathematical',
                'Currency',
                'Arrows'
            ]
        }
    } )
    .then( ... )
    .catch( ... );

# 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';
// A plugin that combines a basic set of special characters.
import { SpecialCharactersEssentials } from '@ckeditor/ckeditor5-special-characters';

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

# Common API

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

# Contribute

The source code of the feature is available at GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-special-characters.