function hook_theme

Same name in other branches
  1. 7.x modules/system/system.api.php \hook_theme()
  2. 9 core/lib/Drupal/Core/Render/theme.api.php \hook_theme()
  3. 8.9.x core/lib/Drupal/Core/Render/theme.api.php \hook_theme()
  4. 10 core/lib/Drupal/Core/Render/theme.api.php \hook_theme()

Register a module or theme's theme implementations.

The implementations declared by this hook specify how a particular render array is to be rendered as HTML.

Parameters

array $existing: An array of existing implementations that may be used for override purposes. This is primarily useful for themes that may wish to examine existing implementations to extract data (such as arguments) so that it may properly register its own, higher priority implementations.

$type: Whether a theme, module, etc. is being processed. This is primarily useful so that themes tell if they are the actual theme being called or a parent theme. May be one of:

  • 'module': A module is being checked for theme implementations.
  • 'base_theme_engine': A theme engine is being checked for a theme that is a parent of the actual theme being used.
  • 'theme_engine': A theme engine is being checked for the actual theme being used.
  • 'base_theme': A base theme is being checked for theme implementations.
  • 'theme': The actual theme in use is being checked.

$theme: The actual name of theme, module, etc. that is being processed.

$path: The directory path of the theme or module, so that it doesn't need to be looked up.

Return value

array An associative array of information about theme implementations. The keys on the outer array are known as "theme hooks". For theme suggestions, instead of the array key being the base theme hook, the key is a theme suggestion name with the format 'base_hook_name__sub_hook_name'. For render elements, the key is the machine name of the render element. The array values are themselves arrays containing information about the theme hook and its implementation. Each information array must contain either a 'variables' element (for using a #theme element) or a 'render element' element (for render elements), but not both. The following elements may be part of each information array:

  • variables: Only used for #theme in render array: an array of variables, where the array keys are the names of the variables, and the array values are the default values if they are not given in the render array. Template implementations receive each array key as a variable in the template file (so they must be legal PHP/Twig variable names). If you are using these variables in a render array, prefix the variable names defined here with a #.
  • render element: Used for render element items only: the name of the renderable element or element tree to pass to the template. This name is used as the name of the variable that holds the renderable element or tree in preprocess and process functions.
  • file: The file that any preprocess implementations reside in. This file will be included prior to the template being rendered, to make sure that the preprocess function (as needed) is actually loaded.
  • path: If specified, overrides the path to the directory that contains the file to be used. This path should be relative to the Drupal root directory. If not provided, the path will be set to the module or theme's templates directory.
  • template: The template name, without 'html.twig' on the end. The extension will be added automatically by the default rendering engine (which is Twig.) If 'path' is specified, 'template' should also be specified. If not specified, a default template name will be assumed. For example, if a module registers the 'search_result' theme hook, 'search-result' will be assigned as its template name.
  • base hook: Used for theme suggestions only: the base theme hook name. Instead of this suggestion's implementation being used directly, the base hook will be invoked with this implementation as its first suggestion. The base hook's files will be included and the base hook's preprocess functions will be called in addition to any suggestion's preprocess functions. If an implementation of hook_theme_suggestions_HOOK() (where HOOK is the base hook) changes the suggestion order, a different suggestion may be used in place of this suggestion. If after hook_theme_suggestions_HOOK() this suggestion remains the first suggestion, then this suggestion's template will be used to generate the rendered output.
  • pattern: A regular expression pattern to be used to allow this theme implementation to have a dynamic name. The default is to use __ to differentiate the dynamic portion of the theme. Implementations can specify a different pattern if required.
  • preprocess functions: A list of functions used to preprocess this data. Ordinarily this won't be used; it's automatically filled in. By default, for a module this will be filled in as template_preprocess_HOOK. For a theme this will be filled in as twig_preprocess and twig_preprocess_HOOK as well as themename_preprocess and themename_preprocess_HOOK.
  • override preprocess functions: Set to TRUE when a theme does NOT want the standard preprocess functions to run. This can be used to give a theme FULL control over how variables are set. For example, if a theme wants total control over how certain variables in the page.html.twig are set, this can be set to true. Keep in mind that when this is used by a theme, that theme becomes responsible for making sure necessary variables are set.
  • type: (automatically derived) Where the theme hook is defined: 'module', 'theme_engine', or 'theme'.
  • theme path: The directory path of the theme or module. If not defined, it is determined during the registry process.
  • deprecated: The deprecated key marks a twig template as deprecated with a custom message.

See also

Theme system overview

hook_theme_registry_alter()

Related topics

Hooks
Define functions that alter the behavior of Drupal core.
14 functions implement hook_theme()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

announcements_feed_theme in core/modules/announcements_feed/announcements_feed.module
Implements hook_theme().
big_pipe_regression_test_theme in core/modules/big_pipe/tests/modules/big_pipe_regression_test/big_pipe_regression_test.module
Implements hook_theme().
book_theme in core/modules/book/book.module
Implements hook_theme().
config_translation_theme in core/modules/config_translation/config_translation.module
Implements hook_theme().
deprecated_twig_template_theme in core/modules/system/tests/modules/deprecated_twig_template/deprecated_twig_template.module
Implements hook_theme().

... See full list

1 invocation of hook_theme()
Registry::processExtension in core/lib/Drupal/Core/Theme/Registry.php
Process a single implementation of hook_theme().

File

core/lib/Drupal/Core/Render/theme.api.php, line 1251

Code

function hook_theme($existing, $type, $theme, $path) : array {
    return [
        'my_module_display' => [
            'variables' => [
                'my_modules' => NULL,
                'topics' => NULL,
                'parents' => NULL,
                'tid' => NULL,
                'sortby' => NULL,
                'my_module_per_page' => NULL,
            ],
        ],
        'my_module_list' => [
            'variables' => [
                'my_modules' => NULL,
                'parents' => NULL,
                'tid' => NULL,
            ],
        ],
        'my_module_icon' => [
            'variables' => [
                'new_posts' => NULL,
                'num_posts' => 0,
                'comment_mode' => 0,
                'sticky' => 0,
            ],
        ],
        'status_report' => [
            'render element' => 'requirements',
            'file' => 'system.admin.inc',
        ],
    ];
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.