CKEditor for Strapi

A Preset defines a specific set of features and appearance for an editor instance. This allows you to offer different editor modes (e.g., HTML vs Markdown) in the Content-Type Builder.

Each Preset object contains:

• name: The name of the preset (used in the schema).
• description: A description shown in the Content-Type Builder.
• editorConfig: The standard CKEditor 5 configuration object (refer to CKEditor documentation for details).
• styles (optional): Additional CSS styles applied to the editor instance after the theme styles.

import { type Preset } from '@_sh/strapi-plugin-ckeditor';

const myCustomPreset: Preset = {
  name: 'myCustomPreset',
  description: 'A custom editor preset',
  editorConfig: {
    licenseKey: 'GPL',
    plugins: [ /* CKEditor plugins */ ],
    toolbar: [ /* toolbar items */ ],
  },
  styles: '.ck { color: red; }',
};

Upgrading to version 8 updates CKEditor from 47.x to 48.x. Most setups require no code changes, but be aware of the following:

• CKEditor 5 Update: If you use custom plugins or presets, consult the official CKEditor 5 migration guide.
• CSS Specificity: CKEditor selectors are now wrapped in :is(). If you override styles via the plugin theme, ensure your rules are still specific enough to apply.
• HTML Output Changes: Table alignment now uses CSS classes instead of inline styles, header cells include a scope attribute, and media embeds use width/height and aspect-ratio instead of padding-bottom. Existing content is not automatically rewritten.
• HTML Sanitization: The default HTML preset now uses dompurify instead of sanitize-html. This allows more elements (images, video, audio, inline styles) in the editor preview. To revert to previous behavior, override htmlEmbed.sanitizeHtml in your custom preset.
• Preset Defaults: The preset field option now has a default value (the first configured preset) instead of a validator. If using setPluginConfig(), the default is the first preset defined, not defaultHtml.
• Dependencies: yup and sanitize-html are no longer dependencies of this plugin. If your code relies on them being installed via this plugin, add them to your project explicitly.
• Node.js Support: Supported versions are now >= 20.0.0 <= 26.x.x.

Version 5 introduces breaking changes, including a new configuration method and the renaming of the default preset to defaultHtml.

Scenario 1: No custom configuration

If you do not use custom configuration, you must update your fields to use the defaultHtml preset to avoid errors.

Option 1 (Recommended): Update your Content-Type schemas manually or via the Content-Type Builder to use defaultHtml instead of default.

Option 2: Apply custom configuration in src/admin/app.[js|tsx] and rename the defaultHtmlPreset.name to default to maintain compatibility with existing schemas.

Scenario 2: Custom configuration

If you use custom configuration, you must migrate from the old object-based presets format to an array-based format.

Key changes for custom config:

• presets is now an array of objects (previously an object).
• The field property in a Preset is replaced by name and description.
• CKEditor packages are no longer on globalThis. You must import them directly from ckeditor5.
• theme and presets are no longer merged with defaults; they overwrite them.
• The style plugin and material color palette have been removed from the default preset.
• The plugin theme now uses Strapi's theme variables.

Move your configuration from config/ckeditor.js into src/admin/app.[js|tsx] using setPluginConfig().

// Example of the new v5 configuration pattern in src/admin/app.tsx
import { Autoformat, Bold, Italic, Essentials, Heading } from 'ckeditor5';
import {
  setPluginConfig,
  defaultHtmlPreset,
  StrapiMediaLib,
  StrapiUploadAdapter,
} from '@_sh/strapi-plugin-ckeditor';

const CKEConfig = () => ({
  presets: [
    {
      ...defaultHtmlPreset,
      editorConfig: {
        ...defaultHtmlPreset.editorConfig,
        toolbar: ['heading', '|', 'bold', 'italic', '|', 'strapiMediaLib', '|', 'undo', 'redo'],
      },
    },
    {
      name: 'myCustomPreset',
      description: 'My custom preset',
      editorConfig: {
        licenseKey: 'GPL',
        plugins: [
          Autoformat,
          Bold,
          Italic,
          Essentials,
          Heading,
          StrapiMediaLib,
          StrapiUploadAdapter,
        ],
        toolbar: ['heading', '|', 'bold', 'italic', '|', 'strapiMediaLib', '|', 'undo', 'redo'],
      },
    },
  ],
});

export default {
  register() {
    setPluginConfig(CKEConfig());
  },
};

The CKEditor plugin configuration must be defined on the front-end (Strapi Admin panel). You can modify the plugin's configuration using setPluginConfig, getPluginPresets, and getPluginTheme.

Key Rules for Configuration:

• Timing: You must invoke configuration functions before the admin panel's bootstrap lifecycle function. It is recommended to call them inside the register lifecycle function.
• Immutability: The configuration becomes immutable after the first invocation of setPluginConfig.
• Overwriting: Providing a new configuration object via setPluginConfig will overwrite the default values for the properties provided (e.g., providing a new presets array will replace all default presets).

Available Functions:

• setPluginConfig(config: PluginConfig): Sets the global plugin configuration.
• getPluginPresets(): Returns the current presets object where keys match preset names.
• getPluginTheme(): Returns the current theme object.

import { setPluginConfig } from '@_sh/strapi-plugin-ckeditor';

export default {
  register() {
    setPluginConfig({
      presets: [/* your presets */],
      theme: { /* your theme */ }
    });
  },
};