## 🔧 Installation
**Strapi v5:**
Add the package to your Strapi application:
```bash
yarn add @_sh/strapi-plugin-ckeditor
```
Then, build the app:
```bash
yarn build
```
**Strapi v4:**
Version 3 of the plugin will remain available for Strapi v4 until March 2026.
Refer to the [**v3 installation guide**](https://github.com/nshenderov/strapi-plugin-ckeditor/blob/3.x.x/README.md#installation)
for setup instructions.
> Note: Version 3 receives only essential bug fixes. The configuration process and available
> features in version 3 differ significantly from the latest plugin versions.
## ✍️ Usage
The field can be found in the Content-Type Builder under the `CUSTOM` tab:
**Presets**
A preset is a set of settings that define the editor's features and appearance. You
can specify a dedicated preset for each field. The available presets can be customized through the
[configuration](#configuration).
The plugin provides two presets out of the box: `Default HTML editor` and `Default Markdown editor`,
each has different output format: HTML and Markdown, respectively. Both presets include
an extensive set of non-premium CKEditor plugins.
Default HTML editor:
Default Markdown editor:
**Responsive images**
The plugin generates `srcset` attribute for inserted images if the image has any `formats` other than `thumbnail`.
**UI language**: If you don't specify the UI language in the editor configuration, the plugin will
default to the Strapi admin's preferred language. If no preference is set, English will be used as a fallback.
**Content language**: i18n for the editor's content language can be enabled by checking the
`Enable localization for this field` option in the Advanced Settings tab.
> 💡 It is important to use the content styles on the publishing side of your application. Otherwise, the content will look different in the editor and for your end users. [Follow the documentation](https://ckeditor.com/docs/ckeditor5/latest/getting-started/setup/css.html#styling-the-published-content).
> To display content from external sources, such as images or videos, in your admin panel,
> you need to configure your `middlewares.js` file.
> [**Check the documentation for details.**](https://docs.strapi.io/dev-docs/configurations/middlewares#security)
## ⚙️ Configuration
The plugin configuration must be defined on the front-end.
The plugin provides a set of functions that allow you to modify the plugin's configuration:
```ts
setPluginConfig(config);
getPluginPresets();
getPluginTheme();
```
**setPluginConfig**
The function, accepts a plugin configuration (`PluginConfig`) that can include an array of presets
and a theme object:
```ts
import { setPluginConfig } from '@_sh/strapi-plugin-ckeditor';
function setPluginConfig(pluginConfig: {
presets: Preset[] | undefined;
theme: Theme | undefined;
}): void;
```
**Key points:**
- The function must be invoked before the admin panel's bootstrap lifecycle function. The general recommendation is to call it inside the admin panel's register lifecycle function.
- Provided properties will overwrite the default configuration values.
- The configuration becomes immutable after the first invocation, preventing further modifications.
**Plugin configuration object** includes optional `presets` and `theme` properties:
```ts
type PluginConfig = {
/**
* Presets are sets of settings that define the editor's features and appearance.
*/
presets?: Preset[];
/**
* Styles applied globally to every editor instance.
*/
theme?: Theme;
};
```
`presets` is an array of objects of type `Preset`. Each preset includes the following properties:
```ts
type Preset = {
/**
* Preset name, displayed in the schema.
*/
name: string;
/**
* Preset description, displayed in the Content-Type Builder.
*/
description: string;
/**
* CKEditor configuration object.
*
* @see {@link https://ckeditor.com/docs/ckeditor5/latest/getting-started/setup/configuration.html | CKEditor documentation}
*/
editorConfig: EditorConfig;
/**
* Additional styles applied to the editor instance after the theme styles.
*/
styles?: EditorStyles;
};
```
`theme` object defines a plugin CSS styles applied to every editor instance. It includes the
following properties:
```ts
/**
* The `common` styles are applied first, followed by `light` or `dark` styles
* according to user preferences, and finally `additional` styles.
*/
type Theme = {
/**
* Core styles.
*/
common?: EditorStyles;
/**
* Styles applied in light mode.
*/
light?: EditorStyles;
/**
* Styles applied in dark mode.
*/
dark?: EditorStyles;
/**
* Additional styles that complement the theme.
*/
additional?: EditorStyles;
};
```
```ts
/**
* Represents styles that can be applied to an editor instance.
* Can be a plain CSS string or an array of interpolations for dynamic styling.
*/
export type EditorStyles = string | Interpolation
