I am trying to develop a Drupal 8 module in which I have to override the html.html.twig template. The idea is that I do not want any of the default html.html.twig template returned instead I only want the custom template returned. I have been spending hours Google hunting and trying to make sense of the many examples and I have gotten myself totally confused.

What is happening is the content of my custom template are being displayed in the default html template so I am seeing the custom content inside the default html template rather than overriding the default content.

For the sake of getting this template override working I have simplified the module as much as possible and simply want to return the contents of a variable into a placeholder in the twig template. Once this override is working I can go back and add the code that will create the correct content to be output into a number of variables in the template.

What I do not understand is exactly how to I override the html.html.twig template.

My module is called unsw_blocks and in the unsw_blocks.module I have the following

function unsw_blocks_theme() {

$theme = [
'unsw_blocks' => [
     'variables' => ['test_var' => NULL],

return $theme;

In the Unsw_blocksController.php have the following

class Unsw_blocksController extends ControllerBase {

  public function unsw_blocks($name) {
  return [
    '#theme' => 'unsw_blocks',
    '#test_var' => $this->t('The variable called test_var simply passes this text itself to the theme template'),

In the custom modules templates directory I have unsw-blocks.html.twig which simply contains

<h1>Testing Template</h1>

<p>test_var: {{ test_var }}</p>

2 Answers 2


AFAIK you can't override html.twig in a module, but you can create module with a route and a controller that returns a Symfony response to bypass this limitation. There is background-information and a code example in this question:

Override html.twig.html within custom module


HI please follow the below steps.

Step 1: create routing file docroot\modules\custom\product\product.routing.yml

  path: '/product/details/{product}'
    _controller: '\Drupal\product\Controller\ProductDetailsController::details'
    _title: 'Product Details'
    _permission: 'access content'
        type: entity:node

Step 2: Create a controller: modules\custom\product\src\Controller\ProductDetailsController.php

   * Callback for route product.custom_form.
  public function details($product) 
    return [
      '#theme' => 'product-details',
      '#content' => [
        '#contextual_links' => [
          'node' => [
            'route_parameters' => ['node' => $product->id()],
      '#product' => $product,

Step 3: In your theme create a file following the directory themes\custom\mytheme\templates\product-details.html.twig

<div class="my-form-class">
    <div class="page-header">
        <h1>{{ product.title.value }}</h1>
            {% if product.field_title_description %}
                {{ product.field_title_description.value }}
            {% endif %}

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.