Defines the CDN to be used for CKEditor 5 assets. The example below shows how to set the CDN to :jsdelivr:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  cdn :jsdelivr
end

It also allows you to define a custom CDN by passing a block with the bundle, version, and path arguments. The example below shows how to define it for the jsdelivr CDN:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  cdn do |bundle, version, path|
    base_url = "https://cdn.jsdelivr.net/npm/#{bundle}@#{version}/dist"

    "#{base_url}/#{path.start_with?('translations/') ? '' : 'browser/'}#{path}"
  end
end

Defines the version of CKEditor 5 to be used. The example below shows how to set the version to 43.2.0:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  version '48.3.1'
end

In order to disable default patches, you can pass the apply_patches: false keyword argument to the version method.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  version '48.3.1', apply_patches: false
end

The patches are defined in the lib/ckeditor5/rails/plugins/patches directory. If you want to apply custom patches, you can use the patch_plugin method.

Defines if automatic upgrades should be enabled. It's disabled for the :default preset by default. The example below shows how to enable automatic upgrades:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  automatic_upgrades
end

It means that the editor will automatically upgrade to the latest version when the gem is updated. It'll upgrade the editor only if the new patch or minor version is released. If you want to disable automatic upgrades, you can pass the enabled: false keyword argument to the automatic_upgrades method.

Version is checked every nth day, where n is the number of days since the last check. Currently it's 4 days.

Defines the license of CKEditor 5. The example below shows how to set the license to GPL:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  gpl
end

Defines the license key of CKEditor 5. It calls premium method internally. The example below shows how to set the license key:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  license_key 'your-license-key'
end

Defines if premium package should be included in JS assets. The example below shows how to add ckeditor5-premium-features to import maps:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  premium
end

Defines the height of the editor. The example below shows how to set the height to 300px:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  editable_height 300
end

Defines the language of the editor. You can pass the language code as an argument. Keep in mind that the UI and content language can be different. The example below shows how to set the Polish language for the UI and content:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  language :pl
end

In order to set the language for the content, you can pass the content keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  language :pl, content: :en
end

The example above sets the Polish language for the UI and content. If pl language was not defined in the translations, the builder will append the language to the list of translations to fetch. In order to prefetch more translations, use the helper below.

Defines the translations of CKEditor 5. You can pass the language codes as arguments. The example below shows how tell integration to fetch Polish and Spanish translations:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  translations :pl, :es
end

⚠️ You need to use language method to set the default language of the editor, as the translations only fetch the translations files and makes them available to later use.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  translations :pl
  language :pl
end

Defines the CKBox plugin to be included in the editor. The example below shows how to include the CKBox plugin:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  ckbox '2.6.0', theme: :lark
end

Defines the type of editor. Available options:

• :classic - classic edytor
• :inline - inline editor
• :decoupled - decoupled editor
• :balloon - balloon editor
• :multiroot - editor with multiple editing areas

The example below sets the editor type to multiroot in the custom preset:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  type :multiroot
end

Defines the toolbar items. You can use predefined items like :undo, :redo, :| or specify custom items. There are a few special items:

• :_ - breakpoint
• :| - separator

The should_group_when_full keyword argument determines whether the toolbar should group items when there is not enough space. It's set to true by default.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
          :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
          :bulletedList, :numberedList, :todoList, :outdent, :indent
end

Keep in mind that the order of items is important, and you should install the corresponding plugins. You can find the list of available plugins in the CKEditor 5 documentation.

If you want to add or prepend items to the existing toolbar, you can use the block syntax:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  toolbar do
    append :selectAll, :|, :selectAll, :selectAll
    # Or prepend: prepend :selectAll, :|, :selectAll, :selectAll
  end
end

If you want to remove items from the toolbar, you can use the remove method:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  toolbar do
    remove :selectAll, :heading #, ...
  end
end

If you want to append groups of items, you can use the group method:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  toolbar do
    group :text_formatting, label: 'Text Formatting', icon: 'threeVerticalDots' do
      append :bold, :italic, :underline, :strikethrough, separator,
             :subscript, :superscript, :removeFormat
    end
  end
end

If you want add new line or the separator, you can use the break_line or separator methods:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  toolbar do
    append :bold, break_line
    append separator, :italic
  end
end

API is identical to the toolbar method, but it's used for block toolbar items. The example below shows how to define block toolbar items:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  block_toolbar :paragraph, :heading, :blockQuote, :|, :bulletedList, :numberedList, :todoList
end

It is useful when you want to use Block Balloon Editor or Block Toolbar features.

API is identical to the toolbar method, but it's used for balloon toolbar items. The example below shows how to define balloon toolbar items:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  balloon_toolbar :bold, :italic, :underline, :link, :insertImage, :mediaEmbed, :insertTable, :blockQuote
end

It is useful when you want to use Balloon Editor or Balloon Toolbar features.

Defines the visibility of the menubar. By default, it's set to true. In order to hide the menubar, you can pass the visible: false keyword argument.

The example below shows how to set the menubar visibility:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  menubar visible: false
end

Allows you to set custom configuration options. You can pass the name of the option and its value as arguments. The ckeditor5_element_ref(selector) helper allows you to reference DOM elements that will be used by the editor's features. It's particularly useful for features that need to check element presence or operate on specific DOM elements.

For example, you can use it to configure font family dropdown to show only fonts available in specific elements:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  configure :fontFamily, {
    supportAllValues: true,
    options: [
      'default',
      'Arial, Helvetica, sans-serif',
      'Courier New, Courier, monospace',
      'Georgia, serif',
      'Lucida Sans Unicode, Lucida Grande, sans-serif',
      'Tahoma, Geneva, sans-serif',
      'Times New Roman, Times, serif',
      'Trebuchet MS, Helvetica, sans-serif',
      'Verdana, Geneva, sans-serif'
    ]
  }
end

Defines a plugin to be included in the editor. You can pass the name of the plugin as an argument. The premium keyword argument determines whether the plugin is premium. The import_name keyword argument specifies the name of the package to import the plugin from.

The example below show how to import Bold plugin from the ckeditor5 npm package:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  plugin :Bold
end

In order to import a plugin from a custom ESM package, you can pass the import_name keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  plugin :YourPlugin, import_name: 'your-package'
end

In order to import a plugin from a custom Window entry, you can pass the window_name keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  plugin :YourPlugin, window_name: 'YourPlugin'
end

If there is no window.YourPlugin object, the plugin will dispatch window event to load. To handle this event, you can use the window.addEventListener method:

window.addEventListener('ckeditor:request-cjs-plugin:YourPlugin', () => {
  window.YourPlugin = (async () => {
    const { Plugin } = await import('ckeditor5');

    return class YourPlugin extends Plugin {
      // Your plugin code
    };
  })();
});

⚠️ The event handler must be attached before the plugin is requested. If the plugin is requested before the event handler is attached, the plugin will not be loaded.

Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments. The keyword arguments are identical to the configuration of the plugin method defined below.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  plugins :Bold, :Italic, :Underline, :Link
end

Methods such as remove, append, and prepend can be used to modify the plugins configuration. To remove a plugin, you can use the remove method with the plugin name as an argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  plugins do
    remove :Heading
  end
end

⚠️ Warning: Use with caution as this is an inline definition of the plugin code, and it can potentially cause XSS vulnerabilities. Only use this method with static, trusted JavaScript code. In order to pass some dynamic data to such plugin, you can use the configure method and override the selected preset in your controller.

The example below shows how to define a custom plugin that doesn't do anything:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  inline_plugin :MyCustomPlugin, <<~JS
    const { Plugin } = await import( 'ckeditor5' );

    return class extends Plugin {
      static get pluginName() {
        return 'MyCustomPlugin';
      }

      init() {
        const config = this.editor.config.get('myCustomPlugin') || {};

        // ... Your plugin code
      }
    }
  JS
end

To configure the custom plugin, use the configure method in your initializer. The example below shows how to configure the myCustomPlugin:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  configure :myCustomPlugin, {
    option1: 'value1',
    option2: 'value2'
  }
end

This approach is resistant to XSS attacks as it avoids inline JavaScript.

Defines an external plugin to be included in the editor. You can pass the name of the plugin as an argument. The script keyword argument specifies the URL of the script to import the plugin from. The import_as keyword argument specifies the name of the package to import the plugin from. The window_name keyword argument specifies the name of the plugin in the window object. The stylesheets keyword argument specifies the URLs of the stylesheets to import.

The example below shows how to define an external plugin that highlights the text:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  external_plugin :MyExternalPlugin,
                  script: 'https://example.com/my-external-plugin.js'
end

In order to import a plugin from a custom ESM package, you can pass the import_as keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  external_plugin :MyExternalPlugin,
                  script: 'https://example.com/my-external-plugin.js',
                  import_as: 'Plugin'
end

It's equivalent to the following JavaScript code:

import { Plugin } from 'my-external-plugin';

In order to import a plugin from a custom Window entry, you can pass the window_name keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  external_plugin :MyExternalPlugin,
                  script: 'https://example.com/my-external-plugin.js',
                  window_name: 'MyExternalPlugin'
end

It's equivalent to the following JavaScript code:

const Plugin = window.MyExternalPlugin;

In order to import a plugin with stylesheets, you can pass the stylesheets keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  external_plugin :MyExternalPlugin,
                  script: 'https://example.com/my-external-plugin.js',
                  stylesheets: ['https://example.com/my-external-plugin.css']
end

Defines a plugin that applies a patch to the specific versions of CKEditor 5. The example below shows how to define a plugin that applies a patch to the 44.1.0 version:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  patch_plugin MyPatchPlugin.new
end

where the MyPatchPlugin should inherit from KEditor5::Rails::Editor::PropsPatchPlugin and implement the initialize method. For example:

class YourPatch < CKEditor5::Rails::Editor::PropsPatchPlugin
  PLUGIN_CODE = <<~JS
    const { Plugin, ColorPickerView, debounce } = await import( 'ckeditor5' );

    return class YourPatch extends Plugin {
      static get pluginName() {
        return 'YourPatch';
      }

      constructor(editor) {
        super(editor);

        // ... your patch
      }
    }
  JS

  def initialize
    super(:YourPatch, PLUGIN_CODE, min_version: nil, max_version: '45.0.0')
  end
end

Defines a method that applies patches to the specific versions of CKEditor 5. The example below shows how to apply patches to the 44.1.0 version:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  apply_integration_patches
end

It's useful when you want to apply patches to the specific versions of CKEditor 5. The patches are defined in the lib/ckeditor5/rails/plugins/patches directory.

Defines the URL for the simple upload adapter. The default endpoint is /uploads and the method is POST. The example below shows how to set the URL to /uploads:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  simple_upload_adapter
  # or: simple_upload_adapter '/uploads'
end

Defines the special characters plugin to be included in the editor. The example below shows how to include the special characters plugin:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  special_characters do
    # Enable built-in packs using symbols
    packs :Text, :Essentials, :Currency, :Mathematical, :Latin

    # Custom groups
    group 'Emoji', label: 'Emoticons' do
      item 'smiley', '😊'
      item 'heart', '❤️'
    end

    group 'Arrows',
          items: [
            { title: 'right arrow', character: '→' },
            { title: 'left arrow', character: '←' }
          ]

    group 'Mixed',
          items: [{ title: 'star', character: '⭐' }],
          label: 'Mixed Characters' do
      item 'heart', '❤️'
    end

    order :Text, :Currency, :Mathematical, :Latin, :Emoji, :Arrows, :Mixed
  end
end

For more info about the special characters plugin, check the official documentation.

Defines the WProofreader plugin to be included in the editor. The example below shows how to include the WProofreader plugin:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  wproofreader serviceId: 'your-service-ID',
               srcUrl: 'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js'
end

The version keyword argument allows you to specify the version of the WProofreader plugin. The cdn keyword argument allows you to specify the CDN to be used for the WProofreader plugin.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  wproofreader version: '2.0.0',
               cdn: 'https://cdn.jsdelivr.net/npm/@ckeditor/ckeditor5-wproofreader@2.0.0/dist',
               serviceId: 'your-service-ID',
               srcUrl: 'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js'
end

If no language is set, the plugin will use the default language of the editor. If you want to set the language of the WProofreader plugin, you can use the language keyword argument:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  wproofreader serviceId: 'your-service-ID',
               srcUrl: 'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js',
               language: :en_US,
               localization: :pl
end

For more info about the WProofreader plugin, check the official documentation.

Allows setting custom translations for editor components, UI elements, and headings. The translations are applied globally since they override the global translation object.

[!NOTE] This helper allows overriding builtin translations of the editor, but translations are overridden globally, as the CKEditor 5 uses a single translation object for all instances of the editor. It's recommended to use the ckeditor5_translation_ref helper to reference the translations in the configuration.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  custom_translations :en, {
    'Heading 1': 'Your custom translation value'
  }

  configure :heading, {
    options: [
      { model: 'heading1', title: ckeditor5_translation_ref('Heading 1') },
      # ...
    ]
  }
end

Defines whether the inline plugins should be compressed. It must be called before the inline_plugin and version methods. The example below shows how to disable compression:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  compression enabled: false

  # ... other configuration
end

⚠️ Compression is enabled by default, and it's recommended to keep it enabled for production environments. It reduces the size of the inline plugins and patches, which improves the loading time of the editor. If you want to disable compression for a specific plugin, you can pass the compress: false keyword argument to the inline_plugin method:

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  inline_plugin :MyCustomPlugin, plugin_code, compress: false
end

Allows you to reference CKEditor 5 translations in the configuration. It's particularly useful when you want to use custom translations in the editor configuration.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  custom_translations :en, {
    'Heading 1': 'Your custom translation value'
  }

  configure :heading, {
    options: [
      { model: 'heading1', title: ckeditor5_translation_ref('Heading 1') },
      # ...
    ]
  }
end

In other words, it allows you to reference DOM elements that will be used by the editor's features. It's particularly useful for features that need to check element presence or operate on specific DOM elements. The primary example is the presence list feature that requires a reference to the element that will be used to display the list.

# config/initializers/ckeditor5.rb

CKEditor5::Rails.configure do
  # ... other configuration

  configure :yourPlugin, {
      element: ckeditor5_element_ref("body")
  }
end

It may be useful when you want to define a preset based on the current user or request.

# app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  def show
    @preset = ckeditor5_preset do
      version '48.3.1'

      toolbar :sourceEditing, :|, :bold, :italic, :underline, :strikethrough,
              :subscript, :superscript, :removeFormat, :|, :bulletedList, :numberedList,
              :fontFamily, :fontSize, :|, :link, :anchor, :|,
              :fontColor, :fontBackgroundColor

      plugins :Essentials, :Paragraph, :Bold, :Italic, :Underline, :Strikethrough,
              :Subscript, :Superscript, :RemoveFormat, :List, :Link, :Font,
              :FontFamily, :FontSize, :FontColor, :FontBackgroundColor, :SourceEditing, :Essentials, :Paragraph
    end
  end
end

In order to use the preset in the view, you can pass it to the ckeditor5_assets helper method:

<!-- app/views/demos/index.html.erb -->

<% content_for :head do %>
  <%= ckeditor5_assets preset: @preset %>
<% end %>

<%= ckeditor5_editor %>

If you want to override the preset defined in the initializer, you can search for the preset by name and then override it (it'll create copy of the preset):

# app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  def show
    @preset = ckeditor5_preset(:default).override do
      version '48.3.1'

      toolbar :sourceEditing, :|, :bold, :italic, :underline, :strikethrough,
              :subscript, :superscript, :removeFormat, :|, :bulletedList, :numberedList,
              :fontFamily, :fontSize, :|, :link, :anchor, :|,
              :fontColor, :fontBackgroundColor

      plugins :Essentials, :Paragraph, :Bold, :Italic, :Underline, :Strikethrough,
              :Subscript, :Superscript, :RemoveFormat, :List, :Link, :Font,
              :FontFamily, :FontSize, :FontColor, :FontBackgroundColor, :SourceEditing, :Essentials, :Paragraph
    end
  end
end

All JS assets defined by the ckeditor5_assets helper method are loaded asynchronously. It means that the assets are loaded in the background without blocking the rendering of the page. However, the CSS assets are loaded synchronously to prevent the flash of unstyled content and ensure that the editor is styled correctly.

It has been achieved by using web components, together with import maps, which are supported by modern browsers. The web components are used to define the editor and its plugins, while the import maps are used to define the dependencies between the assets.

ckeditor5_lazy_javascript_tags helper

This method is slow as content is being loaded on the fly on the client side. Use it only when necessary.

If you want to include the CKEditor 5 JavaScripts and Stylesheets when the editor is being appended to the DOM using Turbolinks, Stimulus, or other JavaScript frameworks, you can use the ckeditor5_lazy_javascript_tags helper method.

This method does not preload the assets, and it's appending web component that loads the assets when the editor is being appended to the DOM. It's useful when turbolinks frame is being replaced or when the editor is being appended to the DOM dynamically.

The example below shows how to include the CKEditor 5 assets lazily:

<!-- app/views/demos/index.html.erb -->

<% content_for :head do %>
  <%= ckeditor5_lazy_javascript_tags %>
<% end %>

<%= turbo_frame_tag 'editor' do %>
  <%= ckeditor5_editor %>
<% end %>

⚠️ Keep in mind that the ckeditor5_lazy_javascript_tags helper method should be included in the head section of the layout and it does not create controller context for the editors. In other words, you have to specify preset every time you use ckeditor5_editor helper (in ckeditor5_assets it's not necessary, as it's inherited by all editors).

If you want to keep inheritance of the presets and enforce integration to inject CKEditor 5 files on the fly, you can use the lazy keyword argument in the ckeditor5_assets helper method:

<!-- app/views/demos/index.html.erb -->

<% content_for :head do %>
  <%= ckeditor5_assets preset: :custom, lazy: true %>
<% end %>

<!-- This time preset will be inherited but stylesheets and js files will be injected on the client side. -->
<%= ckeditor5_editor %>