Drupal Blocks and Block Layout — Managing Regions and Block Placement

In this tutorial, you'll learn Drupal blocks and block layout including block types, theme regions, block placement, creating custom blocks with content, visibility conditions for targeted display, and block theming with Twig templates.

What You'll Learn

• What blocks are and how they fit into Drupal's page architecture
• Theme regions and how blocks are placed within them
• Placing and configuring blocks in the block layout interface
• Creating custom blocks with custom fields
• Block visibility conditions by content type, path, role, and language
• Block Caching strategies for performance
• Block theming with Twig template suggestions

Why It Matters

Blocks are the building blocks of Drupal page layouts -- the title is intentional. Every element outside the main content area on a Drupal page is a block: headers, footers, sidebars, banners, call-to-action sections, and more. Mastering block placement and visibility gives you precise control over what appears where, to whom, and under what conditions.

Real-World Use

A university website uses block visibility conditions to show different content to different audiences. A "Student Resources" block appears only on pages tagged with the "Student" taxonomy term and only for logged-in users with the "student" role. A "Faculty Portal" block appears in the same sidebar but only for faculty. A "Campus Alert" block appears at the top of every page when a system flag is enabled.

Learning Path

flowchart LR
  A[Revisions] --> B[Blocks & Layout]
  B --> C[Menus]
  C --> D[Layout Builder]
  D --> E[Next: Custom Modules]

What are Blocks

Blocks are pieces of content placed in regions of a theme. They can be:

• System blocks: Provided by modules (Search form, Who's online, Main navigation)
• Custom blocks: Created by site builders through the admin UI
• Views blocks: Created from a View display
• Custom block types: Content entities with custom fields

Each block sits in a region defined by the theme. When a page is rendered, the theme wraps each region and its blocks in HTML.

Theme Regions

Each theme defines its own regions. Olivero (Drupal 10's default theme) provides:

Header
├── Site branding (logo, site name, slogan)
├── Primary menu (main navigation)
└── Secondary menu (user menu, login)

Content Area
├── Page title
├── Tabs (admin tabs)
├── Messages (status, warning, error)
└── Main content (rendered page)

Sidebar
├── Sidebar first (left sidebar)
└── Sidebar second (right sidebar)

Footer
├── Footer top (three columns)
└── Footer bottom (copyright, legal links)

Viewing Theme Regions

To see available regions for your theme:

# Via Drush
drush php:eval "
  $theme = \Drupal::service('theme.manager')->getActiveTheme();
  print_r($theme->getRegions());
"

# Or in a Twig template
{# List all available regions #}
{% for region in regions %}
  {{ region }}
{% endfor %}

Block Layout Page

Navigate to Structure > Block layout (or /admin/structure/block).

The Block Layout Table

The block layout page shows all theme regions and the blocks placed in each:

Region: Header
  - Site branding (configurable)
  - Main navigation (configurable)

Region: Sidebar first
  - Search form (configurable)
  - Recent articles (View block)
  - User login (configurable)

Region: Footer
  - Footer menu (configurable)
  - Copyright block (custom)

Dragging to Reorder

Drag blocks within a region to change their order. Drag between regions to move blocks.

Placing Blocks

Click "Place block" in any region to add a new block.

Available Blocks

The dialog lists all available blocks:

System blocks:
  - Breadcrumbs
  - Main page content
  - Messages
  - Primary admin actions
  - Search form
  - User account menu
  - Who's online

Custom blocks:
  - Basic block (create new)
  - Any custom block types you've created

Views blocks:
  - Any View with a block display

List blocks:
  - Any List module blocks

Block Configuration

When placing a block, configure:

# Block configuration
Block description: Recent Articles Sidebar
Title: 'Latest News'  # Override default title, or leave empty for no title
Display title: true

Visibility settings:
  Content type:
    - article: Show on article pages
    - page: Show on basic pages
  Path:
    - /blog: Show on blog pages
    - /news/*: Show on all news subpages
  Role:
    - anonymous: Show to anonymous users only
    - authenticated: Show to logged-in users

Region: Sidebar first
Weight: 0  # Position within region (lower = first)

Custom Blocks

Custom blocks are content entities that can have custom fields.

Creating a Custom Block Type

1. Navigate to Structure > Block types > Add
2. Name: "Call to Action"
3. Machine name: call_to_action

Add fields to the block type:

Block type: Call to Action
Fields:
  - title: Text (plain)
  - field_cta_text: Text (formatted, long)
  - field_cta_link: Link
  - field_cta_background: Image
  - field_cta_icon: Entity reference (media)

Adding Custom Block Content

1. Navigate to Structure > Block layout > Place block
2. Choose: "Call to Action" block type
3. Fill in block content
4. Configure visibility settings
5. Save

Programmatic Custom Block

<?php

use Drupal\block_content\Entity\BlockContent;

// Create a custom block programmatically
$block = BlockContent::create([
  'type' => 'call_to_action',
  'info' => 'Homepage CTA',
  'field_cta_text' => [
    'value' => 'Sign up for our newsletter',
    'format' => 'basic_html',
  ],
  'field_cta_link' => [
    'uri' => 'internal:/newsletter',
    'title' => 'Subscribe Now',
  ],
]);
$block->save();

Block Visibility Conditions

Visibility conditions control where and when blocks appear.

Content Type Visibility

Show a block only on specific content types:

Visibility: Content type
Bundles:
  - article
  - event

Path Visibility

Show or hide blocks based on URL paths:

Visibility: Path
Mode: Show for the listed pages
Pages:
  - /blog
  - /news/*
  - /about
  - /<front>

Use * as a wildcard: /blog/* matches /blog/2026/06/article-title.

Role Visibility

Show blocks based on user roles:

Visibility: Role
Roles:
  - anonymous
  - authenticated
  - editor
  - administrator

Language Visibility

Show blocks only in specific languages:

Visibility: Language
Languages:
  - en
  - fr

Custom Visibility via PHP

<?php

// Implement custom block visibility in a custom module
function mymodule_block_access($block, $operation) {
  if ($operation === 'view' && $block->id() === 'homepage_cta') {
    $node = \Drupal::routeMatch()->getParameter('node');
    if ($node && $node->bundle() === 'article') {
      return \Drupal\Core\Access\AccessResult::allowed();
    }
  }
  return \Drupal\Core\Access\AccessResult::neutral();
}

Block Caching

Blocks have their own caching strategies:

<?php

// In a custom block plugin
public function getCacheContexts() {
  return ['url.path', 'user.roles'];
}

public function getCacheTags() {
  return ['node:42', 'config:block.block.my_block'];
}

public function getCacheMaxAge() {
  return 3600;  // Cache for 1 hour
}

Block caching levels:

• Cache per role: Different content for authenticated vs anonymous
• Cache per page: Block content varies by URL
• Cache per user: Personalized block content
• Cache via tags: Invalidate when related content changes

Block Content Templates

Custom blocks can have dedicated Twig templates.

Template Suggestions

Block templates follow a naming convention:

{# Basic block template #}
block.html.twig

{# Block in specific region #}
block--region-name.html.twig

{# Specific block type #}
block--block-content--basic.html.twig

{# Specific block instance #}
block--block-content--basic--block-id.html.twig

Example Block Template

{# templates/block/block--call-to-action.html.twig #}
<div class="cta-block cta-block--{{ content.field_cta_type }}">
  <div class="cta-block__inner">
    {% if label %}
      <h2 class="cta-block__title">{{ label }}</h2>
    {% endif %}

    <div class="cta-block__text">
      {{ content.field_cta_text }}
    </div>

    {% if content.field_cta_link %}
      <div class="cta-block__link">
        {{ content.field_cta_link }}
      </div>
    {% endif %}
  </div>
</div>

Removing and Reordering Blocks

Removing a Block

1. Navigate to Structure > Block layout
2. Find the block in its region
3. Click the dropdown arrow > Remove block
4. Confirm removal

Blocks remain in the system (as content entities for custom blocks) but are no longer placed.

Reordering Blocks

Drag blocks within a region to reorder. Blocks appear in the order listed, top to bottom. Use the "Weight" field for precise ordering.

Common Mistakes

1. Placing too many blocks in one region: A sidebar with 10 blocks overwhelms users. Keep sidebars focused with 3-5 blocks maximum.
2. Not using visibility conditions effectively: Showing a "Login" block to logged-in users wastes space. Use role visibility to show login only to anonymous users.
3. Creating custom blocks for one-time content: If a block is used on a single page, consider adding the content to that page's body instead of maintaining a separate block.
4. Ignoring block caching: Uncached blocks cause slow page loads. Configure appropriate caching based on the block's content and audience.
5. Using the wrong block type: For a simple text snippet, use a Basic block. For complex layouts with multiple fields, create a custom block type.

Practice Questions

1. What is the difference between a system block and a custom block in Drupal?
2. How would you configure a block that shows only on article pages, only to anonymous users, and only when the URL contains "/blog"?
3. Write the Twig template suggestion pattern to override the template for a custom block type with machine name "call_to_action" placed in the sidebar region.
4. Challenge: Build a complete block-based landing page system. Create a "Hero Banner" block type with fields for Background Image, Headline, Subheadline, CTA Text, CTA Link, and Overlay Color. Create a "Feature Card" block type with Icon, Title, Description, and Link. Create a "Testimonial" block type with Quote, Author Name, Author Title, Author Photo. Place these blocks in the content region of a "Landing Page" content type. Create visibility conditions so the Hero Banner only appears on the front page and the Feature Cards only appear on pages with a specific category. Write Twig templates for each block type.

FAQ

Mini Project

Goal: Build a complete block-based layout for a marketing website.

1. Create custom block types:

   • Hero Banner: Background Image, Headline, Subheadline, CTA Text, CTA URL, Overlay Opacity (select: 0-100%)
   • Feature Card: Icon (image), Title, Description (text long), Link URL
   • Testimonial Slider: Quote (text long), Author Name, Author Title, Author Photo (image)
   • Logo Cloud: Title, Logos (image, unlimited)

2. Place blocks in regions:

   • Header: Hero Banner (front page only)
   • Content: Testimonial Slider (all pages)
   • Sidebar first: Feature Cards (service pages only)
   • Footer: Logo Cloud (all pages)

3. Configure visibility:

   • Hero: Path =
   • Feature Cards: Path = /services/*
   • Testimonial: Role = anonymous, authenticated
   • Logo Cloud: Path = /about, /contact

4. Apply caching per block type

5. Create Twig templates for each block type

6. Test block display across different pages and user roles

What's Next

Blocks are placed on pages, but navigation is how users find those pages. Learn about Menus and Navigation for building site navigation systems, then explore Layout Builder for drag-and-drop page layouts.