How to Create a Custom D11 Theme

Discover how to create a custom D11 theme in 9 simple steps. Learn the theming process from directory setups to styling with this beginner-friendly guide.

Introduction to Drupal 11 Theming

Drupal 11 has arrived with exciting improvements for both developers and site builders. Among the many updates, theme customization remains a key feature that allows you to craft a unique look and feel for your website.

What’s New in Drupal 11?

Drupal 11 introduces refined APIs, improved Twig templates, and even better backward compatibility. These updates make theme development smoother and more intuitive than in earlier versions.

Benefits of a Custom Theme

1. Unique branding and user experience
2. Full control over structure and styles
3. Performance optimizations tailored to your needs
4. Easier integration with front-end frameworks

Prerequisites Before You Start

Before we jump into theming, ensure your development environment is properly configured.

Tools You’ll Need

1. A local development environment like DDEV, XAMPP, or Lando
2. Text editor (VSCode, PhpStorm)
3. Git for version control
4. Access to the Drupal admin interface

Environment Setup Tips

1. Install Drupal 11 using Composer.
2. Use a sub-theme only if you’re extending an existing base theme (like Classy or Stable).
3. Always work in a local development environment.

Step 1 – Set Up the Theme Directory

Navigate to your Drupal root and create a directory under /themes/custom/.

mkdir -p themes/custom/my_custom_theme

Naming Conventions

Stick to lowercase letters, underscores, and no spaces in your theme name. For example: my_custom_theme

File Structure Overview

Your initial folder should contain the following:

1. my_custom_theme.info.yml
2. my_custom_theme.libraries.yml
3. templates/
4. css/ and js/ folders (optional at first)

Step 2 – Create .info.yml File

name: My Custom Theme
type: theme
description: 'A custom theme for Drupal 11.'
core_version_requirement: ^11
base theme: classy
libraries:
  - my_custom_theme/global-styling
regions:
  header: Header
  content: Content
  footer: Footer

Required Fields Explained

1. type: Must be theme
2. core_version_requirement: Use ^11 for Drupal 11
3. regions: Define your page structure

Step 3 – Add Libraries for CSS and JS

Your libraries.yml file registers CSS and JS assets.

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

Attaching Assets to the Theme

Reference this library in your .info.yml file under libraries. Drupal will automatically load these assets.

Step 4 – Define Theme Regions

Edit my_custom_theme.theme file in PHP

function my_custom_theme_theme_suggestions_page_alter(array &$suggestions, array $variables) {
  // Modify template suggestions here
}

Commonly Used Regions

1. header
2. navigation
3. content
4. sidebar_first
5. footer

Step 5 – Create Template Files

Templates define how your theme’s HTML is rendered. Start with page.html.twig and node.html.twig.

<div class="layout-container">
  <header>{{ page.header }}</header>
  <main>{{ page.content }}</main>
  <footer>{{ page.footer }}</footer>
</div>

Step 6 – Add Theme Settings (Optional)

Want custom color pickers or layout toggles? You can expose settings in the admin UI.

Custom Settings in theme-settings.php

function my_custom_theme_form_system_theme_settings_alter(&$form, &$form_state) {
  $form['custom_setting'] = [
    '#type' => 'textfield',
    '#title' => t('Custom Setting'),
    '#default_value' => theme_get_setting('custom_setting'),
  ];
}

Step 7 – Enable and Set Default Theme

Use the admin UI or Drush to enable your theme:

drush theme:enable my_custom_theme
drush config:set system.theme default my_custom_theme

Common Errors and Fixes

1. Check info.yml for YAML errors.
2. Clear cache with drush cr after enabling.

Step 8 – Apply Styling with CSS/SCSS

Organize your styles under /css/ or use SCSS for modular design. You can use Bootstrap or Tailwind CSS if preferred.

Organizing Stylesheets

1. /css/global.css – base styles
2. /css/components/ – modular SCSS
3. /css/layouts/ – grid and structure

Step 9 – Test and Debug Your Theme

Use the Twig Debug Mode by enabling services.yml overrides:

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

Clearing Cache and Troubleshooting

1. Use drush cr often
2. Check logs in admin or /admin/reports/dblog

Common Mistakes to Avoid When Theming

1. Modifying core templates directly
2. Forgetting to define all regions
3. Overloading one template with logic
4. Ignoring accessibility and mobile responsiveness

Useful Modules for Themers

External Resources to Learn More

Drupal Theming Guide – Drupal.org

Check How to Upgrade from D10 to D11

FAQs – How to Create a Custom Drupal 11 Theme in 9 Simple Steps

Q1: Can I use a base theme like Bootstrap with my custom theme?
Yes, you can create a sub-theme of Bootstrap or any base theme if you prefer not to start from scratch.

Q2: Is Drush mandatory for enabling a theme?
No, but it simplifies the process. You can also enable themes via the admin UI.

Q3: Where should I add JavaScript files?
Add them in the libraries.yml file and attach them in your .info.yml.

Q4: Can I switch back to a core theme after enabling mine?
Yes, go to Appearance settings and switch themes anytime.

Q5: Do I need to clear the cache every time I edit templates?
Yes, to see the changes reflected, always clear the cache after updates.

Q6: Is Twig difficult to learn for beginners?
Not really! It’s intuitive and has great documentation, making it beginner-friendly.