CKEditor 5 Phoenix Integration ✨

GitHub code size in bytes NPM Version Hex.pm Version

CKEditor 5 integration library for Phoenix (Elixir) applications. Provides web components and helper functions for seamless editor integration with support for classic, inline, balloon, and decoupled editor types.

[!IMPORTANT] This package is unofficial and not maintained by CKSource. For official CKEditor 5 documentation, visit ckeditor.com. If you encounter any issues in the editor, please report them on the GitHub repository.

CKEditor 5 Classic Editor in Phoenix (Elixir) application

CKEditor 5 Phoenix Integration ✨

Installation 🚀

Choose between two installation methods based on your needs. Both approaches provide the same functionality but differ in how CKEditor 5 assets are loaded and managed.

🏠 Self-hosted

Bundle CKEditor 5 with your application for full control over assets, custom builds, and offline support. This method is recommended for advanced users or production applications with specific requirements. It's also GPL-compliant.

Complete setup:

Add dependency to your mix.exs:

def deps do
  [
    {:ckeditor5_phoenix, "~> 1.21.0"}
  ]
end

Install CKEditor 5

mix ckeditor5.install # --premium --version 47.6.0
# ... or: npm install ckeditor5 --prefix assets

Add ckeditor5.install to assets.setup in mix.exs (if using Mix installer):
```
"assets.setup": ["ckeditor5.install", ... ]
```

Register JavaScript hook in your app.js:

import { Hooks } from 'ckeditor5_phoenix';

const liveSocket = new LiveSocket('/live', Socket, {
  hooks: Hooks,
});

Import styles in your assets/css/app.css:

@import "../../deps/ckeditor5/dist/ckeditor5.css";
/* ... or: @import "../node_modules/ckeditor5/dist/ckeditor5.css"; */

Import module in View

defmodule MyAppWeb.PageHTML do
  # ... your other uses
  use CKEditor5
end

Use in templates (no CDN assets needed):

<.ckeditor id="editor" type="classic" value="<p>Hello world!</p>" />

📡 CDN Distribution

Load CKEditor 5 directly from CKSource's CDN - no build configuration required. This method is ideal for most users who want quick setup and don't need custom builds.

Complete setup:

Add dependency to your mix.exs:

def deps do
  [
    {:ckeditor5_phoenix, "~> 1.21.0"}
  ]
end

Register JavaScript hook in your app.js:

import { Hooks } from 'ckeditor5_phoenix';

const liveSocket = new LiveSocket('/live', Socket, {
  hooks: Hooks,
});

Exclude CKEditor from bundler in your config/config.exs:

config :my_app, MyAppWeb.Endpoint,
  watchers: [
    esbuild: {Esbuild, :install_and_run, [
      :my_app,
      ~w(--external:ckeditor5 --external:ckeditor5-premium-features)
    ]}
  ]

Add license key (see Providing the License Key 🗝️ section)

Import module in View

defmodule MyAppWeb.PageHTML do
  # ... your other uses
  use CKEditor5
end

Use in templates:

<%!-- Load CDN assets in <head> (based on `default` preset) --%>
<.cke_cloud_assets />

<%!-- or with specific features (overrides `default` preset) --%>
<.cke_cloud_assets translations={["pl", "de", "fr"]} premium />

<%!-- or with specific preset --%>
<.cke_cloud_assets preset="inline" />

<%!-- Use editor anywhere in <body> --%>
<.ckeditor id="editor" type="classic" value="<p>Hello world!</p>" />

That's it! 🎉

Basic Usage 🏁

Get started with the most common usage patterns. These examples show how to render editors in your templates and handle real-time content changes.

Simple Editor ✏️

Create a basic editor with default toolbar and features. Perfect for simple content editing without server synchronization.

<%!-- CDN only: Load assets in <head> --%>
<.cke_cloud_assets />

<%!-- Render editor with initial content --%>
<.ckeditor
  id="editor"
  type="classic"
  value="<p>Initial content</p>"
  editable_height="300px"
/>

Watchdog prop 🐶

By default, the <.ckeditor> component uses a built-in watchdog mechanism to automatically restart the editor if it crashes (e.g., due to a JavaScript error). The watchdog periodically saves the editor's content and restores it after a crash, minimizing the risk of data loss for users.

The watchdog is enabled by default. To disable it, set the watchdog prop to false:

<.ckeditor
  type="classic"
  value="<p>Initial content</p>"
  watchdog={false}
/>

Configuration ⚙️

You can configure the editor presets in your config/config.exs file. The default preset is :default, which provides a basic configuration with a toolbar and essential plugins. The preset is a map that contains the editor configuration, including the toolbar items and plugins. There can be multiple presets, and you can switch between them by passing the preset keyword argument to the ckeditor component.

Custom Presets 🧩

In order to override the default preset or add custom presets, you can add the following configuration to your config/config.exs file:

# config/config.exs
config :ckeditor5_phoenix,
  presets: %{
    minimal: %{
      cloud: %{
        version: "46.0.0",
        premium: true,
        translations: ["pl"],
        ckbox: %{
          version: "1.0.0"
        }
      },
      config: %{
        toolbar: [:bold, :italic, :link],
        plugins: [:Bold, :Italic, :Link, :Essentials, :Paragraph]
      }
    },
    full: %{
      config: %{
        toolbar: [
          :heading, :|, :bold, :italic, :underline, :|,
          :link, :insertImage, :insertTable, :|,
          :bulletedList, :numberedList, :blockQuote
        ],
        plugins: [
          :Heading, :Bold, :Italic, :Underline, :Link,
          :ImageBlock, :ImageUpload, :Table, :List, :BlockQuote,
          :Essentials, :Paragraph
        ]
      }
    }
  }

In template:

<.ckeditor preset="minimal" value="<p>Simple editor</p>" />

Dynamic presets 🎯

You can also create dynamic presets that can be modified at runtime. This is useful if you want to change the editor configuration based on user input or other conditions.

defmodule MyApp.PageLive do
  use MyAppWeb, :live_view
  use CKEditor5

  alias CKEditor5.Preset

  def mount(_params, _session, socket) do
    preset = Preset.Parser.parse!(%{
      config: %{
        toolbar: [:bold, :italic, :link],
        plugins: [:Bold, :Italic, :Link, :Essentials, :Paragraph]
      }
    })

    {:ok, assign(socket, preset: preset)}
  end
end

In template:

<.ckeditor preset={@preset} />
````

### Providing the License Key 🗝️

CKEditor 5 requires a license key when using the official CDN or premium features. You can provide the license key in two simple ways:

1. **Environment variable**: Set the `CKEDITOR5_LICENSE_KEY` environment variable before starting your Phoenix app. This is the easiest and most common way.
2. **Preset config**: You can also set the license key directly in your preset configuration in `config/config.exs`:

config :ckeditor5_phoenix,

 presets: %{
   default: %{
     license_key: "your-license-key-here"
   }
 }


If you use CKEditor 5 under the GPL license, you do not need to provide a license key. However, if you choose to set one, it must be set to `GPL`.

If both are set, the preset config takes priority. For more details, see the [CKEditor 5 licensing guide](https://ckeditor.com/docs/ckeditor5/latest/getting-started/licensing/license-and-legal.html).

### Referencing DOM Elements in Config 🏷️

You can reference DOM elements directly in your editor configuration using the special `{ $element: "selector" }` format. This is useful when you want to attach the editor's UI parts (like toolbars or editable areas) to specific elements in your HTML.

# config/config.exs config :ckeditor5_phoenix, presets: %{ # ... other presets minimal: %{ config: %{ # ... other config yourPlugin: %{ toolbar: %{ $element: "#my-toolbar" }, editable: %{ $element: "#my-editable" } }, } } }


This will find the elements with IDs `my-toolbar` and `my-editable` in the DOM and use them for the editor's UI. If the element is not found, a warning will be shown in the console.

## Editor Types 🖊️

CKEditor 5 Phoenix supports four distinct editor types, each designed for specific use cases. Choose the one that best fits your application's layout and functionality requirements.

### Classic editor 📝

Traditional WYSIWYG editor with a fixed toolbar above the editing area. Best for standard content editing scenarios like blog posts, articles, or forms.

![CKEditor 5 Classic Editor in Elixir Phoenix application with Menubar](docs/classic-editor-with-toolbar.png)