Including Partial Templates

Themers often separate templates into multiple partial templates for maintainability, then include them as needed. A common use case is to move the site header and footer into their own files templates, then include them in page.html.twig. Twig's include function is similar to PHP's include function in that it includes the contents of another file.

Process

Let's say you have created following file in your theme folder for the header:

THEME_NAME/templates/includes/header.html.twig

And now you want to include this file in:

page.html.twig

The recommended method

The correct method for Drupal 8 themes is to use Twig namespaces to declare the current theme "templates" directory.

{{ include('@THEME_NAME/includes/header.html.twig') }}

Below is an example taken from a working theme on Drupal.org called Architect.
"@architect" refers to /templates in the working theme (architect) directory.

{{ include('@architect/includes/header.html.twig') }}

A Twig namespace is created in Drupal 8 automatically when installing your theme, pointing to the /templates directory of your theme. Essentially, writing "@theme_name" in a Twig include (like above) will reference the location "your-site.com/themes/custom/theme-name/templates" on your server.

When developing a module, the namespace can be set to @MODULE_NAME to point to a twig template in the modules "template" directory.

{{ include('@MODULE_NAME/includes/header.html.twig') }}

Additional parameters

If you need to pass additional arguments to your included twig template, use the following syntax.

{{ include('@THEME_NAME/includes/form-block.html.twig', {'key': value}) }}

Example:

{{ include('@mytheme/includes/form-block.html.twig', {'display_title': true}) }}

Context

The context of the template including the partial template is included by default, giving the partial template access to the full scope of its parent's variables.

Optionally, you may disallow the context of the current template from being passed to the partial template with the following syntax.

{{ include('@THEME_NAME/includes/form-block.html.twig', with_context = false) }}

You may pass additional variables while disallowing the context of the current template from being passed to the partial template.

{{ include('@THEME_NAME/includes/form-block.html.twig', {'key': value}, with_context = false) }}

The not-recommended method

One possible (but not recommended) method is to concatenate the theme directory and a relative path. While this may work in some cases, it will throw a server error when used within a sub-theme. See #3049414.

{# NOT recommended #}
{{ include(directory ~ '/templates/includes/header.html.twig') }}

The above information may work however it will create a server error if used with a sub-theme.

Extending namespace functionality

As of Drupal 10.3.0, the SDC (Single Directory Components) core module is stable and allows for more flexible and sophisticated ways to organize templates and build reusable components.

For Drupal versions prior to 10.3.0, consider the Components! contributed module as an alternative to SDC.

Both of the aforementioned solutions make use of the Twig embed tag.