DEV Community

Cover image for CKEditor 5 Pitfall: Don't Forget the Paragraph Plugin
Ondřej Chrastina for CKEditor

Posted on Edited on Originally published at ondrej.chrastina.dev

CKEditor 5 Pitfall: Don't Forget the Paragraph Plugin

When you're adding CKEditor 5 to your platform, chances are you're starting simple—maybe testing in a sandbox project or integrating through the excellent CKEditor Builder, or diving into the CKEditor Framework Crash Course.

In my case, I tried both approaches:

Both are fantastic resources. However, there's one small but crucial detail that’s easy to overlook:
💡 You need two plugins to make even a minimal CKEditor 5 setup work:

  • Essentials
  • 🚨 Paragraph (yes, it's not included in Essentials!)
ClassicEditor.create(element, {
    licenseKey: 'GPL',
    plugins: [
        Essentials, // * ✅ Essential
        Paragraph // 🚨 Paragraph 🚨 
    ]
});
Enter fullscreen mode Exit fullscreen mode

The Pitfall: Only Using Essentials

It might seem like the following setup is enough:

// Import the editor.
import {
    ClassicEditor,
    Essentials,
} from 'ckeditor5';

// Import the styles.
import 'ckeditor5/ckeditor5.css';

// Get the HTML element with the ID of 'app'.
const element = document.querySelector('#app');

// Instantiate the editor using the `create` method.
const editor = await ClassicEditor.create(element, {
    licenseKey: 'GPL',
    plugins: [
        Essentials
    ]
});
Enter fullscreen mode Exit fullscreen mode

The editor initializes, but nothing works—no content, no cursor, and no error messages either! 😱

Yes, the configuration on the image is slightly richer, but still behaves the same.
Creation of the CKEditor withouts the Paragraph plugin being used.

Take a look at this case:

“Are you missing something?”
Yes. Yes, you are!

YES, it is in the code docs

(alias) class Essentials
import Essentials
A plugin including all essential editing features. It represents a set of features that enables similar functionalities to a element.<br> It includes:</p> <ul> <li><code>:ui/editorui/accessibilityhelp/accessibilityhelp~AccessibilityHelp</code>,</li> <li><code>:clipboard/clipboard~Clipboard</code>,</li> <li><code>:enter/enter~Enter</code>,</li> <li><code>:select-all/selectall~SelectAll</code>,</li> <li><code>:enter/shiftenter~ShiftEnter</code>,</li> <li><code>:typing/typing~Typing</code>,</li> <li><code>:undo/undo~Undo</code>.</li> </ul> <p>This plugin set does not define any block-level containers (such as <strong>:paragraph/paragraph~Paragraph</strong>). If your editor is supposed to handle block content, make sure to include it.</p> </blockquote> <h2> <a name="the-fix-add-the-paragraph-plugin" href="#the-fix-add-the-paragraph-plugin" class="anchor"> </a> The Fix: Add the Paragraph Plugin 🎉 </h2> <p></p> <div class="highlight"><pre class="highlight javascript"><code><span class="c1">// Import the editor.</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">ClassicEditor</span><span class="p">,</span> <span class="nx">Essentials</span><span class="p">,</span> <span class="nx">Paragraph</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ckeditor5</span><span class="dl">'</span><span class="p">;</span> <span class="c1">// Import the styles.</span> <span class="k">import</span> <span class="dl">'</span><span class="s1">ckeditor5/ckeditor5.css</span><span class="dl">'</span><span class="p">;</span> <span class="c1">// Get the HTML element with the ID of 'app'.</span> <span class="kd">const</span> <span class="nx">element</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nf">querySelector</span><span class="p">(</span><span class="dl">'</span><span class="s1">#app</span><span class="dl">'</span><span class="p">);</span> <span class="c1">// Instantiate the editor using the `create` method.</span> <span class="kd">const</span> <span class="nx">editor</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">ClassicEditor</span><span class="p">.</span><span class="nf">create</span><span class="p">(</span><span class="nx">element</span><span class="p">,</span> <span class="p">{</span> <span class="na">licenseKey</span><span class="p">:</span> <span class="dl">'</span><span class="s1">GPL</span><span class="dl">'</span><span class="p">,</span> <span class="na">plugins</span><span class="p">:</span> <span class="p">[</span> <span class="nx">Essentials</span><span class="p">,</span> <span class="nx">Paragraph</span> <span class="p">]</span> <span class="p">});</span> </code></pre></div> <p></p> <p>And voilà:<br> “Much better!”</p> <p><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6pynght6k45tqi5lymte.png" alt="Showcase of the working CKEditor with thew Paragraph plugin being defined."/></p> <h2> <a name="key-takeaway" href="#key-takeaway" class="anchor"> </a> 🧠 Key Takeaway </h2> <ul> <li><code>Essentials</code> plugin ≠ has everything you need for editing.</li> <li>For a working CKEditor instance, especially one with block content, <strong>add the Paragraph plugin</strong>.</li> <li>Always double-check the docs—even for plugins that sound... well, essential.</li> </ul> <p><em>Keep this in mind as you build your rich text editing experiences! 💡</em></p>

Top comments (0)