Drupal 11 Theming Guide for Beginners: Build and Customize Your First Theme

Drupal 11 offers a modern and flexible theming system that allows you to fully control the look and feel of your website. If you’re new to Drupal, theming might seem complex at first—but once you understand the basics, it becomes a powerful tool for creating custom designs.

This beginner-friendly guide walks you through everything you need to know to start theming in Drupal 11.

What Is Theming in Drupal?

Theming in Drupal is the process of controlling how your website looks. It includes:

• Layout and structure
• Colors and fonts
• Templates and markup
• Styling with CSS
• Optional JavaScript enhancements

Drupal separates content from presentation, which makes it easier to manage design without affecting your data.

Understanding Drupal Themes

A theme is a collection of files that define your site’s design.

Key components of a Drupal theme:

• .info.yml file (theme definition)
• Twig templates (.html.twig)
• CSS stylesheets
• JavaScript files (optional)
• Libraries file (.libraries.yml)

Drupal 11 uses Twig as its templating engine, which replaces older PHP-based templates and improves security and flexibility.

Core vs Custom Themes

Core Themes

Drupal comes with built-in themes such as:

• Olivero (default frontend theme)
• Claro (admin theme)

These are great starting points for beginners.

Custom Themes

A custom theme allows you to:

• Fully control design
• Add custom layouts
• Override default templates

For learning purposes, it’s best to create a sub-theme based on an existing theme like Olivero.

Creating a Custom Theme in Drupal 11

Step 1: Create a Theme Folder

Navigate to:

web/themes/custom

Create a new folder:

my_theme

Step 2: Create the .info.yml File

Inside your theme folder, create:

my_theme.info.yml

Add:

name: My Theme type: theme description: A custom Drupal 11 theme core_version_requirement: ^11 base theme: olivero

This tells Drupal your theme exists and inherits from Olivero.

Step 3: Add a Libraries File

Create:

my_theme.libraries.yml

Example:

global-styling:  css:    theme:      css/style.css: {}

Step 4: Add CSS

Create a folder:

css/style.css

Example:

body {  background-color: #ffffff;  font-family: Arial, sans-serif; }

Step 5: Attach the Library

Edit your .info.yml file:

libraries:  - my_theme/global-styling

Step 6: Enable Your Theme

Go to:

Appearance → Install and set as default

Activate your theme.

Understanding Twig Templates

Twig templates control the HTML output of your site.

Common templates:

• page.html.twig → Overall page layout
• node.html.twig → Content (articles, pages)
• block.html.twig → Blocks
• views-view.html.twig → Views output

Overriding Templates

To customize output:

1. Copy a template from a base theme
2. Place it in your theme folder
3. Modify it

Example:

Override:

node.html.twig

Add:

<article class="custom-node">  <h1>{{ label }}</h1>  <div>{{ content.body }}</div> </article>

Using Twig Effectively

Twig syntax basics:

• {{ }} → Print variables
• {% %} → Logic (if, loops)
• {# #} → Comments

Example:

{% if content.field_image %}  <div class="image">    {{ content.field_image }}  </div> {% endif %}

Working with Regions

Regions define where blocks can be placed.

Add regions in your .info.yml:

regions:  header: Header  content: Content  sidebar: Sidebar  footer: Footer

These regions will appear in the Block Layout UI.

Adding JavaScript (Optional)

You can include JS via libraries:

global-scripts:  js:    js/script.js: {}

Then attach it the same way as CSS.

Debugging Templates

Enable Twig debugging to see template suggestions.

In your services.yml:

twig.config:  debug: true  auto_reload: true  cache: false

This helps you identify which templates to override.

Best Practices for Beginners

• Start with a base theme instead of building from scratch
• Keep CSS organized and modular
• Use meaningful class names
• Avoid editing core or contributed theme files directly
• Clear cache frequently when making changes

Common Mistakes to Avoid

• Forgetting to clear cache after template changes
• Misnaming template files
• Not attaching libraries correctly
• Overcomplicating templates too early

When to Use Advanced Theming Features

As you grow more comfortable, explore:

• Single Directory Components (SDC)
• Layout Builder
• Component-based design systems
• Responsive frameworks

Final Thoughts

Drupal 11 theming may feel overwhelming at first, but it becomes much easier once you understand the building blocks: themes, templates, and libraries.

Start small—create a simple custom theme, tweak a few templates, and gradually expand your skills. With practice, you’ll be able to build fully customized, professional Drupal websites.