Drupal Layout Builder Setup

Drupal Layout Builder Setup

Layout Builder is a built-in Drupal 8.7+ visual page building tool. Allows editors to arrange blocks on a customizable grid of layouts without coding. An alternative to Paragraphs for creating pages with arbitrary structure.

Enabling the Module

drush en layout_builder layout_discovery -y
drush cr

Layout Builder is part of Drupal core — no additional Composer installation needed.

Setup for Content Type

Structure → Content types → [type] → Manage display → Enable Layout Builder → Save.

Two modes:

• Defaults — layout template for all nodes of this type (configured by administrator)
• Allow each content item to have its layout customized — each node can have a unique layout

Working with Sections and Blocks

Layout Builder uses a grid-based sections approach. Each section is a row with configurable number of columns (1, 2, 3, 4, or custom ratios). Blocks are added to each column: node fields, custom blocks, views.

Custom Sections via Layout Discovery

// custom_layouts/layouts/my_hero/my_hero.php
namespace Drupal\custom_layouts\Plugin\Layout;

use Drupal\Core\Layout\LayoutDefault;

/**
 * @Layout(
 *   id = "my_hero_layout",
 *   label = @Translation("Hero + Sidebar"),
 *   category = @Translation("Custom"),
 *   template = "layouts/my-hero",
 *   regions = {
 *     "hero" = { "label" = @Translation("Hero Area") },
 *     "sidebar" = { "label" = @Translation("Sidebar") }
 *   }
 * )
 */
class HeroSidebarLayout extends LayoutDefault {}

Twig template layouts/my-hero.html.twig:

<div class="layout-hero-sidebar">
    <div class="layout-hero-sidebar__hero">
        {{ content.hero }}
    </div>
    <aside class="layout-hero-sidebar__sidebar">
        {{ content.sidebar }}
    </aside>
</div>

Layout Builder Restrictions

The Layout Builder Restrictions module limits which blocks can be added to each section. Without it, an editor can accidentally add an unsuitable block.

composer require drupal/layout_builder_restrictions
drush en layout_builder_restrictions -y

Configuration: Structure → [content type] → Manage display → Layout Builder → Restrictions.

Layout Builder Issues

• SEO: Layout Builder stores data in blob, search engines don't always index complex structures properly
• Performance: without caching, each page with unique layout generates additional database queries
• API: Layout Builder doesn't work well with Headless Drupal — JSON:API output doesn't transmit layout structure

For headless architecture, Paragraphs is better.

Comparison with Paragraphs

Layout Builder is more convenient for marketers — visual drag-and-drop. Paragraphs is more convenient for developers — clean data structure, predictable template output, better API support.

Timeline

Setting up Layout Builder for 2–3 content types with custom sections — 3–4 days.