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 toolbar button configurable panel with a table of selectable special characters.
in the editor below to gain access to aEuro 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
This demo only presents a limited set of features. Visit the full-featured editor example to see more in action.
# 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: '❤️' }
], { 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.
The title of a special character must be unique across the entire special characters set.
The third argument of the SpecialCharacters#addItems()
method is optional. You can use it to specify a label displayed as a category name. It is useful when your editor uses a language other than English. Check out the UI language guide to learn more.
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 to an existing category.
import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
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( /* ... */ );
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 “Mathematical” in the select dropdown. You will see that the category now contains the additional greek letters added in the configuration above.
Greek alphabet letters
Greek alphabet letters are used as math and science symbols.
Examples of greek letters that could be used to describe angles in a triangle:
- Letter name: Alpha, greek letter: α
- Letter name: Beta, greek letter: β
- Letter name: Gamma, greek letter: γ
# 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 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,
// More 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
# 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
The special characters feature is enabled by default in the superbuild only.
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 at GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-special-characters.
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.