Drupal Text Formats and Editors — CKEditor, Filters and Formatting

In this tutorial, you'll learn how Drupal text formats and editors work — from configuring CKEditor toolbars and text filters to creating custom formats with role-based permissions for secure content authoring.

What You'll Learn

• How Drupal text formats (Filtered HTML, Full HTML, Plain text, Restricted HTML) control content output
• Configuring CKEditor toolbar buttons and rows for different user roles
• How text filters process content in sequence and why filter ordering matters
• Creating custom text formats with specific filter configurations
• Text format security and XSS prevention through proper filter selection

Why It Matters

Text formats are one of Drupal's most important security features. When you let authors write content, you need to control what HTML they can use. Without proper text format configuration, a content editor could accidentally insert broken HTML or a malicious user could inject JavaScript through a text field. Text formats give you granular control over exactly which HTML tags, attributes, and styles each role can use. This is how enterprise sites allow some users to embed videos while restricting others to basic paragraph text only.

Real-World Use

A news publishing site with Drupal needs three levels of text format access: journalists writing articles can only use basic formatting (bold, italic, links, blockquotes); senior editors can embed images, tables, and videos; and administrators have Full HTML access for custom code. Each format is assigned to the appropriate role, and CKEditor is configured to show only the buttons each format allows. This prevents a junior reporter from accidentally breaking the page layout with a misplaced div tag.

Learning Path

flowchart LR
  A[Content Types] --> B[Fields]
  B --> C[Taxonomy]
  C --> D[Entity System]
  D --> E[Views]
  E --> F[Media]
  F --> G[Revisions]
  G --> H[Blocks]
  H --> I[Menus]
  I --> J[Layout Builder]
  J --> K[Text Formats & Editors]
  K --> L[Webforms]
  L --> M[URL Aliases]

Understanding Text Formats

A text format in Drupal is a configuration entity that defines two things: which HTML tags and properties are allowed, and which filters are applied to process the content before rendering. Think of a text format as a two-stage pipeline.

First, the format specifies what raw HTML an author can include. Second, it defines a series of filters that transform that HTML before the browser receives it. Filters can convert URLs into links, remove dangerous tags, add line breaks, and more.

Drupal ships with four default text formats:

Filtered HTML is the most common format for trusted authors. It allows a limited set of safe HTML tags like <p>, <a>, <strong>, <em>, and <ul>. The HTML filter removes any tags not in the allowed list.

Full HTML allows almost all HTML tags including <div>, <table>, <script> and <iframe>. This format should only be assigned to trusted administrators because it can execute JavaScript.

Plain text strips all HTML tags and converts line breaks to HTML paragraphs. It is the safest format and suitable for user-generated comments or untrusted input.

Restricted HTML is similar to Filtered HTML but even more restrictive. It is the default for new text fields and anonymous user submissions.

Configuring Text Formats

You manage text formats at Administration > Configuration > Content Authoring > Text formats and editors. The page lists all available formats and shows which roles can use each one.

Click "Configure" next to any format to edit its settings. The configuration page has three sections: Roles, CKEditor profile, and Filter order.

Roles

Check which user roles can use this text format. If a role has no access to any text format, users in that role cannot use text fields at all. This is critical for security — never give anonymous users access to Full HTML.

CKEditor Profile

If you use the CKEditor module, each text format has its own CKEditor configuration. You choose which toolbar buttons appear, whether to use the source editor, and configure advanced options like the styles dropdown.

Filter Order

Filters run in sequence from top to bottom. The order matters because one filter's output becomes another filter's input. For example, if the "Convert URLs to links" filter runs before the "HTML filter," the generated <a> tags from URL conversion will pass through the HTML filter and be removed unless <a> is in the allowed tags list.

CKEditor Configuration

CKEditor is Drupal's default text editor. Go to Configuration > Text formats and editors and click "Configure" beside a text format. The CKEditor section lets you control the editor's behavior.

Toolbar Configuration

The toolbar configuration determines which buttons appear in the editor. Drag and drop buttons between Available buttons and Active toolbar. Common buttons include:

• Bold, Italic, Underline — basic text formatting
• Bulleted List, Numbered List — list creation
• Link, Unlink — hyperlink management
• Blockquote — indented quote blocks
• Source — allows editing raw HTML
• Table — insert tables
• Image — embed images
• Styles — apply predefined CSS classes

Each text format can have a completely different toolbar. A Plain text format would have no toolbar at all, while Full HTML would include the Source button.

# Example CKEditor configuration stored in config:
editor: ckeditor
settings:
  toolbar:
    rows:
      - - Bold
        - Italic
        - Underline
        - Link
        - Blockquote
      - - BulletedList
        - NumberedList
        - Table
        - Source
  plugins:
    - stylescombo
    - sourcedialog

Styles Dropdown

The Styles dropdown in CKEditor lets authors apply CSS classes to content without knowing CSS. You configure which styles appear in the dropdown through the text format settings.

# Example styles configuration:
styles:
  - name: Callout Box
    element: div
    attributes:
      class: callout-box
  - name: Button
    element: a
    attributes:
      class: button primary
  - name: Code Block
    element: pre
  - name: Highlight
    element: span
    attributes:
      class: highlight

When an author selects text and chooses "Callout Box" from the Styles dropdown, CKEditor wraps the selected text in <div class="callout-box">.

Text Filters in Detail

Filters are the processing engines that transform content before it renders. Each filter does one specific job.

Limit Allowed HTML Tags

This is the core security filter. It maintains a whitelist of allowed HTML tags and their permitted attributes. Any tag not in the list is stripped from the output.

# Allowed tags configuration:
filter_settings:
  allowed_html: "<a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id> <p> <br> <span> <img src alt height width>"
  filter_html_help: true
  filter_html_nofollow: true

Note that only tags and attributes listed here will survive. If you forget <img> and an author tries to insert an image, CKEditor may show it, but the filter will strip it on save.

Convert Line Breaks

This filter converts single line breaks to <br> tags and double line breaks to <p> tags. It is useful for authors who type plain text and expect their line breaks to show up in the rendered output.

Convert URLs to Links

Any text that looks like a URL (starting with http://, https://, or www.) is automatically converted into an HTML anchor tag. This saves authors from having to manually create links.

Input:
Visit https://drupal.org for more information.
Output:
Visit <a href="https://drupal.org">https://drupal.org</a> for more information.

Correct Faulty HTML

This filter attempts to fix broken HTML such as unclosed tags, mismatched nesting, and improperly escaped characters. It runs a tidy operation on the HTML. Always place this filter near the end of the processing chain.

Convert Image URLs to Images

Similar to the URL filter, this one finds image URLs and wraps them in <img> tags. The generated <img> tags will include the correct src attribute.

Filter Ordering

Filter order is one of the most common sources of confusion. Filters execute top to bottom. If you place "Limit allowed HTML tags" before "Convert URLs to links," the HTML filter will strip the generated anchor tags unless you have <a> in the allowed list.

Here is the recommended filter order for a typical Filtered HTML format:

Limit Allowed HTML Tags (second to last) Correct Faulty HTML (last) Convert URLs to Links Convert Line Breaks Convert Image URLs to Images

The HTML filter runs near the end to ensure generated HTML from other filters is also checked. The Correct Faulty HTML filter runs last to clean up any remaining issues.

Creating a Custom Text Format

Let us create a custom text format called "Simple HTML" that allows basic formatting but not images or tables.

Go to Configuration > Text formats and editors > Add text format.

# Custom text format configuration:
name: "Simple HTML"
format: simple_html
weight: 2
roles:
  - contributor
  - editor
filters:
  filter_html:
    status: true
    settings:
      allowed_html: "<p> <br> <strong> <em> <a href> <ul> <ol> <li> <blockquote>"
  filter_autop:
    status: true
  filter_url:
    status: true
    settings:
      filter_url_length: 72
  filter_htmlcorrector:
    status: true

This format allows only basic paragraph, bold, italic, links, and list tags. Images, tables, divs, and scripts are blocked. The URL filter auto-links pasted URLs. The HTML corrector fixes broken tags.

Text Format Permissions

Each text format can be assigned to multiple user roles. A user must have access to at least one format to use any text field. If a user needs to use different formats for different fields, they will see a format selector below each text field in the content edit form.

The permission check happens in hook_field_widget_form_alter:

<?php
// Example of checking text format access in a custom module:
use Drupal\filter\Entity\FilterFormat;

function mymodule_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
  if (isset($form['body'])) {
    $format = $form['body']['widget'][0]['format']['format']['#value'];
    $format_entity = FilterFormat::load($format);
    if ($format_entity && $format_entity->access('use')) {
      // User can use this format.
    }
  }
}

CKEditor Plugins

Drupal core includes several CKEditor plugins. Additional plugins can be added through contributed modules.

Built-in Plugins

• Base — core CKEditor functionality
• Image — insert and edit images
• Link — create and manage hyperlinks
• List — ordered and unordered lists
• Table — insert and edit tables
• Source — edit raw HTML source
• Styles Combo — CSS class dropdown
• Language — language markup for multilingual content

Contrib Plugins

• CKEditor Media Embed — embed media from URLs (YouTube, Twitter)
• CKEditor Code Snippet — syntax-highlighted code blocks
• CKEditor Accordion — collapsible content panels
• CKEditor Templates — pre-defined content templates

Editor Per Content Type

You can assign different text formats to different fields on a content type. For example:

• Article body: Filtered HTML with basic toolbar
• Promo text: Plain text (no toolbar)
• Custom HTML block: Full HTML with source editor

This is done by configuring the text format on each individual field's widget settings. Go to the Manage form display tab for the content type and click the gear icon on the text field to change its allowed formats.

Text Format Security

Security is the primary reason Drupal has text formats. Without them, any user who can write content could execute arbitrary JavaScript, load external resources, or break page layouts.

Key security rules:

Never allow anonymous users to use Full HTML. An anonymous commenter could inject <script> tags. Always use the HTML filter. Even for trusted users, the filter catches accidental bad HTML. Use Plain text for user-generated content like comments. It strips everything. Enable filter_html_nofollow on user-generated links to prevent SEO spam.

Common Mistakes

1. Wrong filter order: Placing the HTML filter before URL conversion filters causes generated links to be stripped. The HTML filter should run near the end of the chain.

2. Giving Full HTML to untrusted roles: Assigning Full HTML to authenticated users or commenters exposes the site to XSS Attacks. Only administrators should use Full HTML.

3. Forgetting to allow tags in the HTML filter: You configure CKEditor to show the Image button, but authors cannot save images because the HTML filter strips <img> tags. Always keep filter settings and editor toolbars in sync.

4. Not testing filter order changes: Rearranging filters in production without testing can cause unexpected content rendering. Always test on a staging environment first.

5. Allowing too many tags in the whitelist: Including unnecessary tags like <iframe>, <object>, or <embed> opens security holes. Only allow the minimum set of tags your authors actually need.

Practice Questions

1. Why does filter ordering matter in Drupal text formats? Give an example of two filters that would produce different output depending on their execution order.

2. What is the difference between Filtered HTML and Full HTML, and which roles should have access to each?

3. How would you configure a text format that allows editors to use images and tables but blocks JavaScript and iframes?

4. Challenge: Plan a text format Strategy for a university website with three user roles: professors (write course descriptions), students (post comments), and administrators (manage the homepage). Define which text format each role uses, which HTML tags each format allows, and which CKEditor buttons appear for each.

FAQ

Mini Project

Goal: Create a custom text format with CKEditor for a blog site.

1. Go to Configuration > Text formats and editors > Add text format
2. Name it "Blog Format" and assign it to the Contributor role
3. Enable CKEditor and configure the toolbar with: Bold, Italic, Link, Unlink, BulletedList, NumberedList, Blockquote
4. Add the following filters in order: Convert URLs to Links, Convert Line Breaks, Limit Allowed HTML Tags, Correct Faulty HTML
5. In the HTML filter settings, allow these tags only: <p> <br> <strong> <em> <a href> <ul> <ol> <li> <blockquote>
6. Create an Article content type and assign the Blog Format to the body field
7. Log in as a Contributor and verify that only the configured toolbar buttons appear
8. Try pasting an <img> tag into the source and confirm it gets stripped on save

What's Next

Now that you understand text formats and editors, proceed to building forms with the Webform module. After that, learn about URL aliases and redirects for clean SEO-friendly URLs.