--- category: features menu-title: Special characters --- # Special characters The {@link module:special-characters/specialcharacters~SpecialCharacters} plugin provides a possibility to insert a special character into the rich-text editor. ## Demo Use the editor below to see the {@link module:special-characters/specialcharacters~SpecialCharacters} plugin in action. {@snippet features/special-characters-source} {@snippet features/special-characters} ## Installation To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-special-characters`](https://www.npmjs.com/package/@ckeditor/ckeditor5-special-characters) package: ```plaintext npm install --save @ckeditor/ckeditor5-special-characters ``` And add it to your plugin list configuration: ```js // The plugin provides API for management special characters and their categories. import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters'; // `SpecialCharacters` does not provide any special character. They are delivered by another plugins. // You can import those ones that you want to use in the editor. import SpecialCharactersCurrency from '@ckeditor/ckeditor5-special-characters/src/specialcharacterscurrency'; import SpecialCharactersMathematical from '@ckeditor/ckeditor5-special-characters/src/specialcharactersmathematical'; import SpecialCharactersArrows from '@ckeditor/ckeditor5-special-characters/src/specialcharactersarrows'; import SpecialCharactersLatin from '@ckeditor/ckeditor5-special-characters/src/specialcharacterslatin'; import SpecialCharactersText from '@ckeditor/ckeditor5-special-characters/src/specialcharacterstext'; // Or import the plugin combining basic set of characters. The imports above can be replaced with the `SpecialCharactersEssentials` plugin. import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials'; ClassicEditor .create( document.querySelector( '#editor' ), { plugins: [ SpecialCharacters, ... ], toolbar: [ 'specialCharacters', ... ], } ) .then( ... ) .catch( ... ); ``` Read more about {@link builds/guides/integration/installing-plugins installing plugins}. ## Common API The {@link module:special-characters/specialcharacters~SpecialCharacters} plugin registers the UI button component (`'specialCharacters'`). We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector 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. ## Special characters in the package The `@ckeditor/ckeditor5-special-characters` package provides a few basic special characters grouped into the following categories: - {@link module:special-characters/specialcharactersarrows~SpecialCharactersArrows} – arrows special characters, - {@link module:special-characters/specialcharacterscurrency~SpecialCharactersCurrency} - currency special characters, - {@link module:special-characters/specialcharacterslatin~SpecialCharactersLatin} – Latin special characters, - {@link module:special-characters/specialcharactersmathematical~SpecialCharactersMathematical} – Mathematical special characters, - {@link module:special-characters/specialcharacterstext~SpecialCharactersText} – Text special characters - {@link module:special-characters/specialcharactersessentials~SpecialCharactersEssentials} – combining plugins listed above. ## Adding a new special character category By using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function, you can define a new special characters category. The "All" category name is reserved by the plugin and cannot be used as a new name for special characters category. Let's create a simple plugin that provides the `Emoji` category in the special characters dropdown. ```js import Plugin from '@ckeditor/ckeditor5-core/src/plugin'; export default class SpecialCharactersEmoji extends Plugin { static get pluginName() { return 'SpecialCharactersEmoji'; } init() { this.editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [ { title: 'smiley face', character: '😊' }, { title: 'rocket', character: '🚀' }, { title: 'basketball', character: '🏀' }, { title: 'floppy disk', character: '💾' }, { title: 'hearth', character: '❤' } ] ); } } ``` After adding the above plugin into the editor, the new special characters category will be available in the dropdown. A title of a special character must be unique across the entire special characters set. ### Custom special characters category demo Use the special character icon in the editor's toolbar then select `Emoji` in the select dropdown in order to insert a emoji into the editor. {@snippet features/special-characters-new-category} ## Adding a new special characters to existing category By using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function, you can also add new special characters into existing category. ```js class SpecialCharactersArrowsExtended extends Plugin { static get pluginName() { return 'SpecialCharactersArrowsExtended'; } init() { // The `Arrows` category is provided by the `SpecialCharactersArrows` plugin. this.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: '↓' } ] ); } } ``` A title of a special character must be unique across the entire special characters set. ### Extending existing special characters category category demo Use the special character icon in the editor's toolbar then select `Arrows` in the select dropdown in order to add new arrows. {@snippet features/special-characters-extended-category} ## Contribute The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-special-characters.