Drupal Paragraphs vs Layout Builder: When and How to Use Each

Drupal offers multiple ways to build flexible, editor-friendly pages. Two of the most powerful tools are Paragraphs and Layout Builder. Both solve different problems, and understanding when to use which — or how to combine them — is key to building scalable Drupal sites.

This article explains the differences, strengths, weaknesses, and best practices for using Paragraphs and Layout Builder in real-world Drupal projects.

What Is the Paragraphs Module?

The Paragraphs module allows developers and site builders to create reusable content components.

Think of Paragraphs as structured building blocks:

• Text blocks
• Image + text sections
• Hero banners
• Call-to-action blocks
• Galleries, FAQs, feature lists

Each Paragraph type is an entity with its own fields and Twig template.

How Paragraphs Work

1. Install the Paragraphs module
2. Create Paragraph types (e.g. Hero, Text, CTA)
3. Add a Paragraph field to a content type
4. Limit which Paragraph types editors can use
5. Editors add, reorder, and fill components directly in the node edit form

Paragraphs can be nested, reused, and themed independently using template suggestions like:

paragraph--hero.html.twig

Benefits of Paragraphs

• Structured, predictable content
• Easy form-based editing
• Reusable components
• Clean separation of content and presentation
• Ideal for large-scale content sites

Paragraphs are especially effective when consistency matters more than layout freedom.

What Is Layout Builder?

Layout Builder is a core Drupal module that controls page structure and layout.

If Paragraphs define what content exists, Layout Builder defines where and how it appears.

What Layout Builder Allows You to Do

• Create page sections
• Choose layouts (1 column, 2 columns, 3 columns, etc.)
• Place blocks into regions
• Control spacing, backgrounds, and section-level styles
• Preview page structure visually

Editors work in a visual canvas instead of a traditional form, arranging sections and blocks before saving.

Why Teams Use Layout Builder

• High design flexibility
• Perfect for landing pages and marketing content
• Visual preview before publishing
• Supports personalization and dynamic layouts

Layout Builder shines when each page has a unique structure.

Paragraphs vs Layout Builder: Key Differences

Paragraphs focus on content integrity, while Layout Builder focuses on visual composition.

Editor Experience Comparison

Paragraphs

• Familiar form-based editing
• Clear field structure
• Lower risk of layout mistakes
• Ideal for non-technical editors

Layout Builder

• Visual drag-and-drop experience
• Editors control structure and placement
• Requires guidelines and training
• Better for marketing teams

The editor experience alone can determine which approach fits your organization best.

When to Use Paragraphs

Choose Paragraphs if your site has:

• Blogs or news articles
• Product detail pages
• Documentation
• Content types with fixed layouts
• A strong need for consistency

Paragraphs are fast to build, easy to maintain, and scale well across large content collections.

When Layout Builder Is the Better Choice

Layout Builder is ideal when:

• Every page looks different
• Layout experimentation is required
• Editors need visual control
• Spacing, backgrounds, and sections matter
• Personalization or A/B testing is planned

Typical use cases include landing pages, homepages, and campaign pages.

Using Paragraphs and Layout Builder Together

The most robust Drupal architectures use both.

The Hybrid Approach

1. Paragraphs define reusable content components
2. Custom Block Types contain Paragraph fields
3. Blocks are placed using Layout Builder
4. Layout Builder controls structure, not content

This approach provides:

• Structured content
• Flexible layouts
• Reusability
• Long-term maintainability

You can introduce Layout Builder without rebuilding existing Paragraph-based content.

Best Practices for Combining Both

• Paragraphs should never control layout
• Layout decisions belong to Layout Builder sections
• Use a limited set of layouts
• Restrict editor options intentionally
• Treat Paragraphs as part of a design system

A clear separation of responsibilities keeps the site stable as it grows.

Code Examples: Paragraphs + Layout Builder in Practice

Below are practical code snippets showing how Paragraphs and Layout Builder are typically implemented in real projects.

Paragraph Twig Template Example

Each Paragraph type should have a clean, semantic Twig template.

paragraph--hero.html.twig

<section class="component component-hero">
  {% if content.field_title %}
    <h1 class="component-hero__title">{{ content.field_title }}</h1>
  {% endif %}

  {% if content.field_text %}
    <div class="component-hero__text">
      {{ content.field_text }}
    </div>
  {% endif %}

  {% if content.field_cta_link %}
    <div class="component-hero__cta">
      {{ content.field_cta_link }}
    </div>
  {% endif %}
</section>

Best practice:

• No grid or column logic in Paragraph templates
• Only semantic markup and component-level classes

Preprocess for Paragraphs

Use preprocess functions to prepare data and keep Twig clean.

mytheme.theme

function mytheme_preprocess_paragraph(array &$variables) {
  $paragraph = $variables['paragraph'];

  // Add a modifier class based on paragraph bundle.
  $bundle = $paragraph->bundle();
  $variables['attributes']['class'][] = 'component--' . $bundle;

  // Example: boolean field to control alignment.
  if ($paragraph->hasField('field_centered') && !$paragraph->get('field_centered')->isEmpty()) {
    if ($paragraph->get('field_centered')->value) {
      $variables['attributes']['class'][] = 'component--centered';
    }
  }
}

This approach avoids conditional logic in Twig and keeps styling consistent.

Custom Block Type with Paragraphs

Create a custom block type (e.g. Content Section) and add a Paragraph field:

• Block type: content_section
• Field: field_components (Paragraphs)
• Allowed Paragraph types: Text, Image, CTA

This block becomes the bridge between Paragraphs and Layout Builder.

Layout Builder Section Classes

Layout Builder allows section-level classes for spacing and background control.

Example section classes:

section section--light section--padded

CSS example:

.section--light {
  background-color: var(--color-light);
}

.section--padded {
  padding: clamp(2rem, 5vw, 6rem);
}

Rule: backgrounds and spacing belong to sections, not Paragraphs.

Recommended Architecture Overview

Node
 └─ Layout Builder
     └─ Section
         └─ Custom Block
             └─ Paragraph field
                 └─ Paragraph types

This structure scales well, supports reuse, and keeps responsibilities clear.

Layout Builder Block Plugin Example

Below is a practical example of a custom Layout Builder block plugin that can be placed inside sections. This is useful when you need logic-driven blocks (not editor-managed UI blocks) that still fit cleanly into the Paragraphs + Layout Builder architecture.

Example: Custom Block Plugin

src/Plugin/Block/ContentSectionBlock.php

<?php

namespace Drupal\my_module\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/
 * Provides a Content Section block.
 *
 * @Block(
 *   id = "content_section_block",
 *   admin_label = @Translation("Content Section Block"),
 *   category = @Translation("Custom")
 * )
 */
class ContentSectionBlock extends BlockBase {

  /
   * {@inheritdoc}
   */
  public function build() {
    return [
      '#theme' => 'content_section_block',
      '#items' => [
        'title' => $this->t('Example block title'),
        'text' => $this->t('This block can be placed inside Layout Builder sections.'),
      ],
    ];
  }

}

Block Twig Template

content-section-block.html.twig

<section class="component component-content-section">
  <h2>{{ items.title }}</h2>
  <p>{{ items.text }}</p>
</section>

Block Plugin vs Custom Block Type

Use a Block Plugin when:

• You need dynamic logic (permissions, conditions, APIs)

• Content is not editor-managed

• Data is computed programmatically

Use a Custom Block Type when:

• Editors manage the content

• Paragraphs are used inside blocks

• Translations and revisions are required

Production rule:

Custom Block Types + Paragraphs are the default choice.
Block Plugins are the exception.

Final Thoughts

When choosing between Paragraphs and Layout Builder, think in terms of responsibility:

• Consistent design → Paragraphs
• Flexible layouts → Layout Builder
• Complex sites → Both together

Drupal does not force you to choose one path. Used thoughtfully, Paragraphs and Layout Builder complement each other and enable clean, scalable, editor-friendly websites.

A strong Drupal site is not built on tools alone, but on clear architecture and intentional constraints.