Slash commands

The slash commands feature lets you execute a predefined command by writing its name or alias directly in the editor. When you type a slash (/), the suggested commands are displayed in a panel next to it. You can also type a phrase after the / to filter the results in the panel and to easily find the desired command.

# Demo

Type the / character to invoke a panel with predefined commands. Then, filter the result list by typing more characters after the slash, for example: /list. Slash commands can also apply templates or styles defined in the editor.

# Installation

After installing the editor, add the feature to your plugin list and toolbar configuration:

import { ClassicEditor, Mention } from 'ckeditor5';
import { SlashCommand } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SlashCommand, Mention, /* ... */ ],

        // Provide the licence key (see explanation below)
        licenseKey: '<YOUR_LICENSE_KEY>',

        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the License key and activation guide for details.

# Configuration

Although the slash commands feature is based on the mention feature, it does not require any additional configuration to work. In particular, the / marker is configured automatically as well as the list of default slash commands that will work right away (as long as they are enabled in the editor).

However, if you want to modify this list, it is possible to easily add or remove commands through configuration. It is also possible to limit the number of commands displayed in the panel.

# Adding slash commands

It is possible to add both commands registered in the editor and commands that execute custom logic. The parameter you should use for custom commands is slashCommand.extraCommands.

# Editor commands

To add an editor command as a slash command, besides the id and the title you have to provide the commandName parameter. The example below shows how to add a bold slash command:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        slashCommand: {
            extraCommands: [
                {
                    id: 'bold',
                    title: 'Bold',
                    commandName: 'bold',
                    // ...
                },
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Proxy commands

To add a proxy command (a command that executes custom logic), besides the id and the title you have to provide a callback function for the execute parameter. If you do not provide an execute parameter for a proxy command, the editor will throw an error when the user tries to execute it.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        slashCommand: {
            extraCommands: [
                {
                    id: 'alert',
                    title: 'Alert',
                    execute: editor => { console.log( 'Custom logic was executed.' ) }
                    // ...
                },
                // More extra commands.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Removing slash commands

To remove a command from the default list of slash commands, add its name to the array of removed commands (slashCommand.removeCommands). The command will only be removed from the list of default slash commands, and not from the editor.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        slashCommand: {
            removeCommands: [ 'heading', 'paragraph', /* ... */ ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Limiting displayed command list

By default, all available slash commands are displayed in the panel. If you want to limit the number of commands displayed to the user, use the slashCommand.dropdownLimit parameter. It will determine the number of displayed items.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        slashCommand: {
            dropdownLimit: 4
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Single slash command configuration

There are some more optional parameters of a single slash command entry you might find useful when configuring your own commands:

• aliases – To extend command filtering in the panel.
• description – Helpful if a title is not descriptive enough.
• icon – To visually customize your own command.
• isEnabled – To provide custom logic and decide when the command is displayed in the panel.

Here is an example of how you can use them:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        slashCommand: {
            extraCommands: [
                {
                    id: 'bold',
                    title: 'Bold',
                    execute: editor => { /* Custom logic. */ },
                    aliases: [ 'strong' ],
                    description: 'Style the text in bold.',
                    icon: customIcon,
                    isEnabled: editor => { /* Custom logic. */ }
                },
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Sorting and filtering

By default, slash commands are sorted alphabetically by title. The order changes when the user starts filtering. Slash commands matched by id are displayed first, then sorted by title, then by aliases, and finally by description.

# Integration with other features

Slash commands are integrated with the template and style features. It means that all templates and styles can be applied also using the corresponding slash command.

# Related features

You may want to check the following similar productivity features of CKEditor 5:

• Autoformatting – Lets you quickly apply formatting to the content you are writing.
• Automatic text transformation – Enables automatic turning of snippets such as (tm) into ™ and "foo" into “foo”.