CKEditor5 Template
A CKEditor 5 plugin for Drupal that enables inserting predefined HTML content templates into the rich text editor through a convenient toolbar dropdown.
ckeditor5_template
Install
composer require 'drupal/ckeditor5_template:^1.0'
Overview
CKEditor5 Template is a contributed Drupal module that integrates template insertion functionality into CKEditor 5. It is the successor to the legacy ckeditor_template module, which only supported CKEditor 4. This module allows content editors to quickly insert predefined HTML snippets, such as commonly used text blocks, tables, or formatted content structures, directly from the editor toolbar.
The module adds a customizable "Template" button to the CKEditor 5 toolbar. When clicked, it displays a dropdown menu populated with templates defined in an external JSON file. Each template can have its own icon, title, description (shown as tooltip), and HTML content. Content editors can simply click a template to insert it at the current cursor position in the editor.
Site administrators can configure which JSON template file to use per text format, allowing different sets of templates for different content types or user roles. The toolbar button appearance can also be customized, including whether to show a text label next to the icon.
Features
- Adds a Template toolbar button with dropdown menu to CKEditor 5
- Supports unlimited custom HTML templates defined in a JSON file
- Each template can have a custom SVG icon, title, description tooltip, and HTML content
- Configurable per text format, allowing different template sets for different use cases
- Templates are loaded dynamically from an external JSON file
- Toolbar button can display an optional text label alongside the icon
- Includes an example template JSON file to get started quickly
- Dropdown menu supports scrolling when many templates are defined
- Works with Drupal 10.3+ and Drupal 11
Use Cases
Standardized content blocks for marketing teams
Marketing teams often need to insert standardized promotional content, call-to-action blocks, or branded content sections. Create templates for common marketing elements like newsletter signup boxes, product highlight blocks, or promotional banners. This ensures brand consistency across all content while saving time for content creators.
Legal and compliance text insertion
Organizations that need to include standard legal text, disclaimers, copyright notices, or compliance statements can create templates for these recurring text blocks. This ensures the exact approved wording is used every time and reduces the risk of errors or omissions.
Technical documentation boilerplate
For sites with technical documentation, create templates for common structures like code examples with explanatory text, warning/note/tip callout boxes, step-by-step instruction formats, or API documentation patterns. This helps maintain consistent documentation style across the site.
Press release and news article formats
News and media sites can provide templates for standard press release formats, interview quote blocks, image attribution patterns, or article section headers. This helps maintain journalistic style standards while speeding up content creation.
Email newsletter content blocks
When creating content that will be used in email newsletters, templates can provide pre-formatted sections that are known to render correctly in email clients, including table-based layouts, styled headers, and call-to-action buttons.
Multilingual content with consistent structure
For multilingual sites, templates can help ensure that translated content maintains the same structural format across languages. Translators can focus on the text content while the HTML structure remains consistent.
Tips
- Create your template JSON file in a theme or custom module directory rather than in the ckeditor5_template module folder to prevent losing changes during module updates
- Use meaningful and descriptive template titles since they appear in the dropdown menu and should be instantly recognizable to content editors
- Include custom SVG icons for templates to make them visually distinguishable in the dropdown menu
- Keep template HTML simple and semantic - complex styling should be handled by your theme's CSS, not inline styles in templates
- Test templates with all your enabled text filters to ensure the HTML output is not stripped or altered unexpectedly
- For sites with many templates, organize them logically in the JSON file as they appear in order in the dropdown
- Consider creating different template files for different text formats (e.g., simpler templates for basic text formats, more complex ones for full HTML formats)
- The dropdown menu automatically scrolls when you have many templates, limited to 50% of the viewport height
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format}
The Template plugin settings are embedded within the CKEditor 5 toolbar configuration for each text format. After adding the Template button to the active toolbar, clicking its gear icon reveals the configuration options for the template file location and toolbar button appearance.
Troubleshooting 5
Ensure the template file path is relative to the Drupal root directory and starts with a forward slash (e.g., /sites/default/files/templates/my-templates.json). Verify the file exists at that location and has proper read permissions.
Check that your JSON file is valid JSON format. Use a JSON validator to verify the syntax. Ensure each template has at least a 'title' and 'html' property. Check the browser console for JavaScript errors that might indicate issues loading the template file.
This usually indicates the template JSON file cannot be fetched. Check the browser's Network tab in developer tools to see if the JSON file request is failing. Common causes are incorrect file paths, missing files, or server permission issues.
Your text format's filters may be modifying the HTML. Check which filters are enabled (e.g., 'Limit allowed HTML tags') and ensure they permit the HTML elements used in your templates. You may need to add allowed tags to your filter configuration.
Ensure your icon value is valid SVG content starting with '<svg'. The entire SVG markup must be included as a string in the JSON. Invalid SVG will cause the module to fall back to the default template icon.
Security Notes 4
- Template HTML content is inserted directly into the editor without sanitization at the plugin level. Ensure your text format has appropriate filters enabled to sanitize output when content is displayed
- Only trusted administrators should have access to modify template JSON files, as they can contain arbitrary HTML including scripts
- The template file must be accessible via HTTP request from the browser. Do not store template files containing sensitive information in publicly accessible locations
- Consider using Drupal's configuration system or a custom module to manage templates if you need version control and audit trails for template changes