cyberangles blog

CKEditor 5: How to Insert HTML (Where’s the Source Mode?) – Equivalent of Source Editing Area Plugin

CKEditor 5 is a powerful, modern rich text editor widely used in web applications for its flexibility, extensibility, and user-friendly interface. Unlike its predecessor, CKEditor 4, which included a built-in "Source" button for direct HTML editing (often called "Source Mode"), CKEditor 5 takes a modular approach. This design choice prioritizes security, performance, and customization but can leave users wondering: "Where did the source mode go?"

If you’re migrating from CKEditor 4 or new to CKEditor 5 and need to insert or edit raw HTML, this guide will demystify the process. We’ll explore why CKEditor 5 lacks a default source mode, introduce its official equivalent—the Source Editing plugin—and walk through step-by-step instructions to install, configure, and use it. We’ll also cover alternatives, troubleshooting, and security considerations to ensure you can safely and effectively work with HTML in CKEditor 5.

2026-02

Table of Contents#

  1. Why CKEditor 5 Doesn’t Have a Built-In "Source Mode"?
  2. The Equivalent: CKEditor 5’s Source Editing Plugin
  3. Step 1: Install the Source Editing Plugin
  4. Step 2: Configure the Editor to Include Source Editing
  5. Step 3: Using the Source Editing Mode
  6. Troubleshooting: Common Issues & Fixes
  7. Alternatives to the Source Editing Plugin
  8. Security Considerations
  9. Conclusion
  10. References

Why CKEditor 5 Doesn’t Have a Built-In "Source Mode"?#

CKEditor 4 included a "Source" button by default, allowing users to toggle between WYSIWYG and raw HTML editing. CKEditor 5, however, intentionally omits this feature in its core builds. Here’s why:

  • Modularity: CKEditor 5 is built on a plugin-based architecture. Core builds (e.g., Classic, Inline) include only essential features to keep the editor lightweight. Advanced features like source editing are optional plugins.
  • Security: Raw HTML editing poses risks (e.g., XSS attacks). CKEditor 5’s default configuration uses the Advanced Content Filter (ACF) to sanitize content, preventing malicious code. A built-in source mode would bypass this filter by default, which CKEditor 5 avoids for safety.
  • User Experience: Most users don’t need raw HTML access. CKEditor 5 prioritizes WYSIWYG editing, with source mode as a power-user tool.

The Equivalent: CKEditor 5’s Source Editing Plugin#

If you need to edit HTML directly, CKEditor 5 provides an official solution: the Source Editing plugin. This plugin adds a "Source" button to the toolbar, enabling users to switch between WYSIWYG and HTML editing modes—just like CKEditor 4’s "Source Mode."

Key features of the Source Editing plugin:

  • Toggle between WYSIWYG and HTML views.
  • Edit raw HTML directly in a code editor-like interface.
  • Preserves formatting when switching modes (with caveats, covered later).
  • Integrates with CKEditor 5’s ACF (so unsafe HTML may still be filtered).

Step 1: Install the Source Editing Plugin#

The Source Editing plugin is not included in CKEditor 5’s default builds (e.g., the Classic Editor build). You’ll need to install it via npm (or yarn) and add it to your editor configuration.

Prerequisites#

  • A CKEditor 5 setup (e.g., Classic, Inline, or Custom build).
  • Node.js and npm/yarn installed (for package management).

Installation Command#

Run this command in your project directory to install the plugin:

npm install @ckeditor/ckeditor5-source-editing --save
# or
yarn add @ckeditor/ckeditor5-source-editing

Step 2: Configure the Editor to Include Source Editing#

Next, add the Source Editing plugin to your editor’s configuration. Below are examples for common setups.

Example 1: Classic Editor (Most Common)#

If you’re using the Classic Editor, update your editor initialization code to include SourceEditing in the plugins array and add the "sourceEditing" button to the toolbar.

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import SourceEditing from '@ckeditor/ckeditor5-source-editing/src/sourceediting'; // Import the plugin
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
 
ClassicEditor
  .create( document.querySelector( '#editor' ), {
    plugins: [ Essentials, Paragraph, Bold, Italic, SourceEditing ], // Add SourceEditing here
    toolbar: [ 'bold', 'italic', 'sourceEditing' ] // Add the "sourceEditing" button to the toolbar
  } )
  .catch( error => {
    console.error( error );
  } );

Example 2: Custom Builds (Using ckeditor5-custom-build)#

If you’re using a custom build generated via the CKEditor 5 Online Builder, you can add the Source Editing plugin during the build process:

  1. Go to the Online Builder.
  2. Select your base editor (e.g., Classic).
  3. In the "Plugins" tab, search for "Source Editing" and check the box.
  4. Complete the build process and download the custom package.

Step 3: Using the Source Editing Mode#

Once configured, the "Source" button will appear in the editor toolbar. Here’s how to use it:

1. Switch to Source Mode#

Click the "Source" button in the toolbar. The WYSIWYG editor will replace the content area with a plain text field containing the raw HTML of your document.

Source Mode Toggle
Figure 1: The "Source" button in the CKEditor 5 toolbar (appears after installing the plugin).

2. Edit HTML#

Type or paste your HTML directly into the source mode text field. For example:

<p>This is a <strong>custom HTML</strong> snippet with a <a href="https://example.com">link</a>.</p>
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

3. Switch Back to WYSIWYG Mode#

Click the "Source" button again to return to WYSIWYG mode. CKEditor 5 will render your HTML as formatted content.

4. Save or Retrieve the HTML#

To save or use the edited HTML, use the editor.getData() method (or your editor’s save mechanism). For example:

editor.getData(); // Returns the HTML content (e.g., "<p>This is...")

Troubleshooting: Common Issues & Fixes#

Issue 1: "Source" Button Not Appearing#

  • Cause: The plugin isn’t installed or added to the plugins array.
  • Fix: Ensure @ckeditor/ckeditor5-source-editing is installed and listed in the plugins configuration (see Step 2).

Issue 2: HTML Is Stripped When Switching Modes#

  • Cause: CKEditor 5’s Advanced Content Filter (ACF) is sanitizing "unsafe" or "unallowed" HTML tags/attributes.
  • Fix: Configure ACF to allow the tags/attributes you need. For example, to allow <iframe> and class attributes:
ClassicEditor
  .create( document.querySelector( '#editor' ), {
    plugins: [ Essentials, Paragraph, SourceEditing ],
    toolbar: [ 'sourceEditing' ],
    // Allow <iframe> and class attributes globally
    allowedContent: true, // Disables ACF (not recommended for untrusted users)
    // OR granular control (recommended):
    // allowedContent: {
    //   p: { classes: true },
    //   iframe: { attributes: [ 'src', 'width', 'height' ] }
    // }
  } )

Note: Disabling ACF (allowedContent: true) is risky for public users. Use granular rules instead.

Issue 3: Source Mode Crashes or Freezes#

  • Cause: Invalid HTML (e.g., unclosed tags) can break the editor.
  • Fix: Validate your HTML before pasting (use tools like W3C HTML Validator).

Alternatives to the Source Editing Plugin#

If the Source Editing plugin doesn’t meet your needs (e.g., you need programmatic HTML insertion), consider these alternatives:

1. Programmatic HTML Insertion (API)#

Use CKEditor 5’s API to set or get HTML content without a UI:

// Set HTML content
editor.setData( '<p>Programmatically inserted <strong>HTML</strong>.</p>' );
 
// Get HTML content
const htmlContent = editor.getData();
console.log( htmlContent ); // Output: "<p>Programmatically inserted <strong>HTML</strong>.</p>"

2. Third-Party Plugins#

Some community plugins extend HTML editing (e.g., ckeditor5-html5-embed for embedding raw HTML snippets).

3. Custom Toolbar Buttons#

Add a custom button to insert predefined HTML snippets (e.g., a "Insert Table" button that injects <table> HTML).

Security Considerations#

Allowing raw HTML editing is powerful but risky:

  • XSS Attacks: Malicious users can inject scripts (e.g., <script>alert('XSS')</script>).
  • Broken Layouts: Invalid HTML can break your site’s design.

Best Practices:

  • Restrict source mode access to trusted users (e.g., admins, not public users).
  • Use ACF to limit allowed tags/attributes (never disable ACF for untrusted users).
  • Sanitize content server-side (e.g., with DOMPurify) before storage/rendering.

Conclusion#

CKEditor 5’s "Source Mode" equivalent is the official Source Editing plugin. By installing and configuring this plugin, you can toggle between WYSIWYG and HTML editing modes, just like in CKEditor 4. Remember to:

  • Install the plugin via npm.
  • Add it to your editor’s plugins and toolbar.
  • Configure ACF to allow necessary HTML.
  • Prioritize security by restricting access and sanitizing content.

With these steps, you’ll master HTML insertion in CKEditor 5 while keeping your application safe and performant.

References#