Drupal Theming

Existing core theme hook (table, item_list, links)? Use #theme with the core hook name. No need to define your own hook_theme().

return ['#theme' => 'table', '#header' => $header, '#rows' => $rows];

Render element (form elements, containers)? Use #type. These are standardized components with built-in rendering.

return ['#type' => 'html_tag', '#tag' => 'h2', '#value' => $this->t('Title')];

WRONG: Returning raw HTML strings from controllers (return '<div>Hello</div>';). Strings bypass caching, theme overrides, altering hooks, and security filtering. RIGHT: Always return render arrays. Even simple output should use #markup or #plain_text, which integrate with Drupal's render pipeline.

CRITICAL: When you define custom theme hooks via hook_theme(), you MUST actually USE them by returning render arrays with '#theme' => 'your_hook_name' from controllers, block build() methods, or preprocess functions. Declaring a theme hook without using #theme in a render array means the template is never rendered. ALSO: Always attach your CSS library in the SAME render array via '#attached' => ['library' => ['module_name/library_name']]. A .libraries.yml file without #attached means your CSS is never loaded.

Render arrays -- the core concept

Render arrays are NOT HTML. They are declarative descriptions that Drupal renders through its pipeline (applying cache metadata, security filtering, theme overrides, and asset attachment).

Keys starting with # are properties:

• #theme -- which theme hook renders this
• #markup -- simple sanitized HTML
• #plain_text -- fully escaped text
• #type -- render element type
• #cache -- cache metadata (tags, contexts, max-age)
• #attached -- libraries, drupalSettings
• #prefix, #suffix -- HTML wrappers
• #access -- boolean or AccessResult controlling visibility
• #weight -- ordering among siblings

Keys NOT starting with # are children (nested render arrays):

$build = [
  '#type' => 'container',
  'heading' => ['#markup' => '<h2>Title</h2>'],
  'content' => ['#markup' => '<p>Body text</p>'],
];

Children are rendered in #weight order and output is concatenated.

Defining a theme hook (hook_theme)

Implement hook_theme() in your .module file. This defines the data contract between PHP and your Twig template.

Complete hook_theme() example

// hello_world.module

/**
 * Implements hook_theme().
 */
function hello_world_theme($existing, $type, $theme, $path) {
  return [
    'hello_world_salutation' => [
      'variables' => [
        'salutation' => NULL,
        'target' => NULL,
        'overridden' => FALSE,
      ],
    ],
  ];
}

Rules:

• The hook name (hello_world_salutation) becomes the #theme value in render arrays
• variables defines every variable the template can use, with default values
• Default values should be NULL, empty arrays, or FALSE -- never leave them undefined
• Multiple theme hooks can be returned from a single hook_theme() implementation

WRONG: Omitting variables in hook_theme(). Every variable the template uses must be declared with a default value, or it will be undefined in Twig and cause silent failures. RIGHT: Declare all variables with defaults: 'variables' => ['title' => NULL, 'items' => []]. The variables array IS the template's API contract.

Template naming and location

Drupal maps theme hook names to template filenames using a strict convention:

The rule: Underscores in hook name become hyphens in template filename. Extension is always .html.twig. Templates go in the templates/ directory inside your module.

WRONG: Template name not matching hook name. Hook my_module_block requires template my-module-block.html.twig, not my_module_block.html.twig or myModuleBlock.html.twig. RIGHT: Convert every underscore to a hyphen. Place the file in templates/. Drupal will not find the template if the naming convention is wrong.

Twig template patterns

Basic template with attributes and conditionals

{# templates/hello-world-salutation.html.twig #}
<div{{ attributes }}>
  {{ salutation }}
  {% if target %}
    <span class="salutation--target">{{ target }}</span>
  {% endif %}
  {% if overridden %}
    <em>{{ 'Overridden'|t }}</em>
  {% endif %}
</div>

Key Twig syntax

Auto-escaping is on by default. This is a security feature. Do NOT use |raw unless you are certain the content has already been sanitized by Drupal's render pipeline.

Attributes object

The attributes variable is an Attribute object passed to templates. It renders HTML attributes and supports:

{# Add classes #}
<div{{ attributes.addClass('my-class', 'another-class') }}>

{# Check for a class #}
{% if attributes.hasClass('active') %}

{# Set arbitrary attribute #}
<div{{ attributes.setAttribute('role', 'banner') }}>

Preprocess functions

Preprocess functions prepare data for templates. They run before the template renders and can add computed variables, set default attributes, or transform data.

Naming convention

• template_preprocess_HOOK(&$variables) -- default preprocessor (in .module file)
• MODULE_preprocess_HOOK(&$variables) -- module-specific preprocessor

Example: adding CSS classes in preprocess

// hello_world.module

/**
 * Prepares variables for hello_world_salutation templates.
 *
 * Default template: hello-world-salutation.html.twig.
 */
function template_preprocess_hello_world_salutation(&$variables) {
  $variables['attributes']['class'][] = 'salutation';
  if ($variables['overridden']) {
    $variables['attributes']['class'][] = 'salutation--overridden';
  }
}

The $variables['attributes'] array is automatically converted to an Attribute object before the template renders.

Libraries API (CSS/JS attachment)

Never include CSS or JS with inline <script> or <style> tags. Drupal uses the Libraries API for all asset management.

Step 1: Define a library in module_name.libraries.yml

# hello_world.libraries.yml
hello_world_clock:
  version: 1.x
  css:
    component:
      css/hello_world_clock.css: {}
  js:
    js/hello_world_clock.js: {}
  dependencies:
    - core/jquery
    - core/drupal
    - core/once

CSS weight categories (determines load order):

• base -- CSS reset, normalize
• layout -- page structure, grid
• component -- discrete UI components (most common)
• state -- active, hover, disabled states
• theme -- visual styling, colors, fonts

Step 2: Attach the library to a render array

$build = [
  '#theme' => 'hello_world_salutation',
  '#salutation' => $salutation,
  '#attached' => [
    'library' => ['hello_world/hello_world_clock'],
  ],
];

The library name format is module_name/library_name.

Library load ordering and defer

When a library externalizes a dependency as a global variable (e.g., Vue loaded separately from the consuming bundle), be careful with defer and header attributes:

WRONG: Using { attributes: { defer: true } } on a library that provides a global variable (like Vue) consumed by IIFE-format bundles in the footer. Deferred scripts execute AFTER non-deferred footer scripts, so the consuming bundle runs before the global is defined — causing "X is not defined" errors. RIGHT: Omit defer on libraries that provide globals consumed by other scripts. Use header: true and weight: -20 to ensure the global loads first. Drupal's library dependency system handles load ordering — defer breaks it by changing execution timing.

# WRONG: defer causes Vue to execute AFTER kanban.js