Package Exports

@_sh/strapi-plugin-ckeditor/package.json
@_sh/strapi-plugin-ckeditor/strapi-admin
@_sh/strapi-plugin-ckeditor/strapi-server

Readme

CKEditor 5 for Strapi

Integrates CKEditor 5 into your Strapi project as a fully customizable custom field. (Unofficial integration)

👋 Get Started

Features
Installation
Usage
Configuration
Contributing
Migration
Requirements

✨ Features

Media library integration
Responsive images support
Strapi theme switching support
Supports custom styles for the editor
Supports i18n and different UI translations
Allows custom editor configrations
Plugins extensibility

🔧 Installation

Add the package to your Strapi application:

npm install @_sh/strapi-plugin-ckeditor

yarn add @_sh/strapi-plugin-ckeditor

Then build the app:

npm run build

yarn build

✍️ Usage

Default preset:

⚙️ Configuration

It is highly recommended to explore the official CKEditor5 documentation and the Strapi Custom Field API

The plugin configuration should be defined in your-app/config/ckeditor.js|ts

By default, the plugin provides one preset, which can be modified in the config file.

You can also add new presets in the config file.

The plugin exposes all CKEditor packages to the global variable SH_CKE.

The config file must define a function called CKEConfig that returns the configuration object.

The structure of the configuration object is as follows:

{
    dontMergePresets:bool,
    dontMergeTheme:bool,
    presets:{
        default:{
            field:{...},
            styles:string,
            editorConfig:{...},
        },
        ...
    }
    theme:{
        common:string,
        light:string,
        dark:string,
        additional:string,
    }
}

Every preset in the presets object contains three properties:

field (object) Registers this configuration version in the Admin panel.
styles (string) Styles applied to the editor in this version.
editorConfig (object) The CKEditor configuration.

The theme object is used to modify the default global theme of the plugin. It contains four properties:

common (string) Styles applied to the editor to ensure proper appearance of the input.
light (string) Styles applied to the editor when Strapi is in light mode.
dark (string) Styles applied to the editor when Strapi is in dark mode.
additional (string) Additional styles to further enhance the editors appearance.

By default, everything defined in the user’s configuration is merged with the default configuration object. These two properties allow you to prevent this behavior:

dontMergePresets (bool)
dontMergeTheme (bool)

Since Strapi uses i18n for translation, the ignorei18n property is added to the editorConfig.language object. This property allows you to manually set the content language, bypassing i18n. The language object looks like this:

language:{
    ignorei18n (bool),
    ui (string),
    content (string)
}

The language determination follows this logic:

Plugin UI language: language.ui -> preferred language -> 'en'
Content language: ignorei18n ? language.content : i18n -> language.ui

Example of adding a new editor configuration:

ckeditor.js

const CKEConfig = () => ({
    presets:{
        myCustomPreset:{
            field: {
                key: "myCustomPreset",
                value: "myCustomPreset",
                metadatas: {
                    intlLabel: {
                        id: "ckeditor5.preset.myCustomPreset.label",
                        defaultMessage: "My custom preset",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                heading: {
                    options: [
                        { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                        { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                        { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                        { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                        { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                    ]
                },
                image: {
                    toolbar: [
                        'imageStyle:inline',
                        'imageStyle:block',
                        'imageStyle:side',
                        '|',
                        'toggleImageCaption',
                        'imageTextAlternative'
                    ]
                },
                table: {
                    contentToolbar: [
                        'tableColumn',
                        'tableRow',
                        'mergeTableCells',
                        '|',
                        'toggleTableCaption'
                    ]
                }
            }
        }
    }
})

Example of changing buttons, modifying the plugin list, and adding styles in the default preset:

ckeditor.js

const CKEConfig = () => ({
    presets:{
        default:{
            styles:`
                --ck-focus-ring:3px dashed #5CB176;

                .ck.ck-content.ck-editor__editable {
                  &.ck-focused:not(.ck-editor__nested-editable) {
                    border: var(--ck-focus-ring) !important;
                  }
                }
                .ck.ck-content.ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline.ck-blurred{
                  min-height: 400px;
                  max-height: 400px;
                }
                .ck.ck-content.ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline.ck-focused{
                  min-height: 400px;
                  max-height: 1700px;
                }
            `,
            editorConfig:{
                plugins: [
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ]
            }
        }
    }
})

📂 Default preset: admin/src/Input/presets/default.js

📂 Default editor styles: admin/src/Input/theme

💡 To display content from an external source in your admin panel, you should configure your middlewares.js. Explore the documentation for more information

Adding plugins

Your plugin must be available in the global.

Example of adding the Timestamp plugin:

Create the plugin:

// your-app/src/admin/timestamp.js

class Timestamp extends SH_CKE.Plugin {
    init() {
        const editor = this.editor;
        // The button must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'timestamp', () => {
            // The button will be an instance of ButtonView.
            const button = new SH_CKE.ButtonView();

            button.set( {
                label: 'Timestamp',
                withText: true
            } );

            // Execute a callback function when the button is clicked.
            button.on( 'execute', () => {
                const now = new Date();

                // Change the model using the model writer.
                editor.model.change( writer => {

                    // Insert the text at the user's current position.
                    editor.model.insertContent( writer.createText( now.toString() ) );
                } );
            } );

            return button;
        } );
    }
}

globalThis.Timestamp = Timestamp;

Import the plugin:

// your-app/src/admin/app.js

import './timestamp.js'

const config = {};

const bootstrap = (app) => {};

export default {
  config,
  bootstrap,
};

Add the new plugin to your preset:

ckeditor.js

// your-app/config/ckeditor.js

const CKEConfig = () => ({
    presets: {
        myCustomPreset:{
            field: {
                key: "myCustomPreset",
                value: "myCustomPreset",
                metadatas: {
                    intlLabel: {
                    id: "ckeditor5.preset.myCustomPreset.label",
                    defaultMessage: "My custom preset",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    Timestamp,
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'timestamp',
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                
                // ...
            }
        },
  }
})

Then rebuild the application:

npm run build

yarn build

Alternatively, you can define your plugin like this:

ckeditor.js

const CKEConfig = () => {
  class Timestamp extends SH_CKE.Plugin {
    init() {
      const editor = this.editor;
      // The button must be registered among the UI components of the editor
      // to be displayed in the toolbar.
      editor.ui.componentFactory.add("timestamp", () => {
        // The button will be an instance of ButtonView.
        const button = new SH_CKE.ButtonView();

        button.set({
          label: "Timestamp",
          withText: true,
        });

        // Execute a callback function when the button is clicked.
        button.on("execute", () => {
          const now = new Date();

          // Change the model using the model writer.
          editor.model.change((writer) => {
            // Insert the text at the user's current position.
            editor.model.insertContent(writer.createText(now.toString()));
          });
        });

        return button;
      });
    }
  }

  return {
    presets: {
        myCustomPreset:{
          field: {
            key: "myCustomPreset",
            value: "myCustomPreset",
            metadatas: {
              intlLabel: {
                id: "ckeditor5.preset.myCustomPreset.label",
                defaultMessage: "My custom preset",
              },
            },
          },
            editorConfig:{
                plugins: [
                    Timestamp,
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'timestamp',
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                
                ...
            }
        },
  }
}

🛠 Contributing

This section explains how to set up your environment if you want to contribute to this package.

Clone the repository:

git clone https://github.com/nshenderov/strapi-plugin-ckeditor.git ./strapi-plugin-ckeditor

Navigate to the downloaded folder:

cd ./strapi-plugin-ckeditor

Install dependencies:

yarn install

Link the plugin to your project:

In the plugin directory, run:

yarn watch:link

In your project directory, run:

yarn dlx yalc add --link @_sh/strapi-plugin-ckeditor && yarn install

Rebuild the project and start the server:

yarn build
yarn develop

✈️ Migration

From v2 to v3

The default editor configurations (toolbar, toolbarBalloon, blockBalloon) have been removed and now there is only one preset by default. You will need to update your fields in the Content-Type Builder
Config file extension has changed from .txt to .js or .ts
Configuration object properties have been renamed:
- configsOverwrite -> dontMergePresets
- themeOverwrite -> dontMergeTheme
- configs -> presets
From v3 instead of globalThis.CKEditorConfig = {..}, the config file must define a function called CKEConfig that returns the configuration object.

Example of the new configuration file:

ckeditor.js

const CKEConfig = () => ({
    presets:{
        myCustomPreset:{
            field: {
                key: "myCustomPreset",
                value: "myCustomPreset",
                metadatas: {
                    intlLabel: {
                        id: "ckeditor5.preset.myCustomPreset.label",
                        defaultMessage: "My custom preset",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    SH_CKE.Autoformat,
                    SH_CKE.Bold,
                    SH_CKE.Italic,
                    SH_CKE.Essentials,
                    SH_CKE.Heading,
                    SH_CKE.Image,
                    SH_CKE.ImageCaption,
                    SH_CKE.ImageStyle,
                    SH_CKE.ImageToolbar,
                    SH_CKE.ImageUpload,
                    SH_CKE.Indent,
                    SH_CKE.Link,
                    SH_CKE.List,
                    SH_CKE.Paragraph,
                    SH_CKE.PasteFromOffice,
                    SH_CKE.Table,
                    SH_CKE.TableToolbar,
                    SH_CKE.TableColumnResize,
                    SH_CKE.TableCaption,
                    SH_CKE.StrapiMediaLib,
                    SH_CKE.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                heading: {
                    options: [
                        { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                        { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                        { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                        { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                        { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                    ]
                },
                image: {
                    toolbar: [
                        'imageStyle:inline',
                        'imageStyle:block',
                        'imageStyle:side',
                        '|',
                        'toggleImageCaption',
                        'imageTextAlternative'
                    ]
                },
                table: {
                    contentToolbar: [
                        'tableColumn',
                        'tableRow',
                        'mergeTableCells',
                        '|',
                        'toggleTableCaption'
                    ]
                }
            }
        }
    }
})

⚠️ Requirements

Strapi v5.0.0+

Node >=18.0.0 <=20.x.x