---
title: "DocHeaderComponent"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:docheadercomponent@main"
source: "ApiOverview/Backend/BackendModules/DocHeaderComponent.rst"
rendered: "2026-09-24T12:36:55+00:00"
---

# `DocHeaderComponent` {#docheadercomponent}

The `\TYPO3\CMS\Backend\Template\Components\DocHeaderComponent` can be
used to display a standardized header section in a backend module with buttons,
menus etc. It can also be used to hide the header section in case it is
not desired to display it.

![](../../../Images/ManualScreenshots/Backend/DocHeaderComponent.png)

You can get the `DocHeaderComponent` with
[\\TYPO3\\CMS\\Backend\\Template\\ModuleTemplate::getDocHeaderComponent](https://docs.typo3.org/permalink/t3coreapi:typo3-cms-backend-template-moduletemplate-getdocheadercomponent@main)
from your module template.

**Table of contents**

-   [DocHeaderComponent API](https://docs.typo3.org/permalink/t3coreapi:docheadercomponent-api@main)
-   [Setting the breadcrumb of a backend module](https://docs.typo3.org/permalink/t3coreapi:setting-the-breadcrumb-of-a-backend-module@main)
-   [Layout of the backend module header](https://docs.typo3.org/permalink/t3coreapi:layout-of-the-backend-module-header@main)
-   [Adding module actions and a language selector to the module header](https://docs.typo3.org/permalink/t3coreapi:adding-module-actions-and-a-language-selector-to-the-module-header@main)
-   [Example: build a module header with buttons and a menu](https://docs.typo3.org/permalink/t3coreapi:example-build-a-module-header-with-buttons-and-a-menu@main)

## `DocHeaderComponent` API {#docheadercomponent-api}

It has the following methods:

-   **class DocHeaderComponent**

    -   *Fully qualified name:* `\TYPO3\CMS\Backend\Template\Components\DocHeaderComponent`

    Document header component for backend modules.

    This component manages the header area of backend module views, providing:
    \- Breadcrumb navigation (via BreadcrumbContext)
    \- Button bar for action buttons (save, close, delete, etc.)
    \- Drop-down menus for module-specific actions

    The component can be enabled or disabled to control visibility of the entire
    document header. It integrates with the ModuleTemplate to provide a consistent
    header across all backend modules.

    Usage in a controller:

    ```php
    public function __construct(
        protected readonly ComponentFactory $componentFactory,
    ) }

    public function myAction(): ResponseInterface
    {
        $view = $this->moduleTemplateFactory->create($request);
        $docHeader = $view->getDocHeaderComponent();

        // Set breadcrumb for a page
        $docHeader->setPageBreadcrumb($pageInfo);

        // Add action buttons using ComponentFactory
        $buttonBar = $docHeader->getButtonBar();
        $saveButton = $this->componentFactory->createSaveButton('editform');
        $buttonBar->addButton($saveButton, ButtonBar::BUTTON_POSITION_LEFT, 1);
    }
    ```

    -   **setBreadcrumbContext(?\\TYPO3\\CMS\\Backend\\Breadcrumb\\BreadcrumbContext $breadcrumbContext)**

        Sets the breadcrumb context for rendering.

        This is the main API for providing breadcrumb information.

        For common scenarios, use the convenience methods instead:
        \- setPageBreadcrumb() for page records
        \- setRecordBreadcrumb() for any record
        \- setResourceBreadcrumb() for files or folders

        -   *param $breadcrumbContext:* The breadcrumb context

    -   **setPageBreadcrumb(array $pageRecord)**

        Sets breadcrumb from a page record array.

        Example:
        $view->getDocHeaderComponent()->setPageBreadcrumb($pageInfo);

        -   *param $pageRecord:* The page record array (must contain 'uid')

    -   **setRecordBreadcrumb(string $table, int $uid)**

        Sets breadcrumb for editing a record.

        Example:
        $view->getDocHeaderComponent()->setRecordBreadcrumb('tt_content', 123);

        -   *param $table:* The table name
        -   *param $uid:* The record UID

    -   **setResourceBreadcrumb(\\TYPO3\\CMS\\Core\\Resource\\ResourceInterface $resource)**

        Sets breadcrumb for any resource (file or folder).

        Example:
        $view->getDocHeaderComponent()->setResourceBreadcrumb($file);
        $view->getDocHeaderComponent()->setResourceBreadcrumb($folder);

        -   *param $resource:* The resource (file or folder)

    -   **addBreadcrumbSuffixNode(\\TYPO3\\CMS\\Backend\\Dto\\Breadcrumb\\BreadcrumbNode $node)**

        Adds a suffix node to the current breadcrumb context.

        Suffix nodes are appended after the main breadcrumb trail and are useful for:
        \- Indicating "Create New" actions
        \- Showing "Edit Multiple" states
        \- Adding custom contextual information

        Example:

        > $docHeader->setPageBreadcrumb($pageInfo);
        > $docHeader->addBreadcrumbSuffixNode(
        >     new BreadcrumbNode(
        >         identifier: 'new',
        >         label: 'Create New Content Element',
        >         icon: 'actions-add'
        >     )
        > );

        Note: This creates or modifies the breadcrumb context. If you need to build
        a complete context, use BreadcrumbFactory instead.

        -   *param $node:* The node to append

    -   **getMenuRegistry()**

        Returns the menu registry for adding drop-down menus to the document header.

        *Returns:* `TYPO3CMSBackendTemplateComponentsMenuRegistry`

    -   **getButtonBar()**

        Returns the button bar for adding action buttons to the document header.

        The button bar supports multiple button positions (left, right) and groups
        to organize buttons logically.

        *Returns:* `TYPO3CMSBackendTemplateComponentsButtonBar`

    -   **isEnabled()**

        Determines whether this component is enabled and should be rendered.

        When disabled, the entire document header (including breadcrumbs, buttons,
        and menus) will not be displayed in the backend module.

        *Returns:* `bool`

    -   **enable()**

        Enables this component for rendering.

    -   **disable()**

        Disables this component to prevent rendering.

    -   **setLanguageSelector(?\\TYPO3\\CMS\\Backend\\Template\\Components\\ComponentInterface $component)**

        -   *param $component:* the component

    -   **getLanguageSelector()**

        *Returns:* `?TYPO3CMSBackendTemplateComponentsComponentInterface`

    -   **setShortcutContext(string $routeIdentifier, string $displayName, array $arguments = \[\])**

        Sets the context for the automatic shortcut button.

        Controllers can use this method to provide shortcut information without
        manually creating and adding the shortcut button. The button will be
        automatically added to the button bar in the correct position.

        Example:

        > $docHeader->setShortcutContext('site_configuration.edit', sprintf('Edit site: %s', $siteIdentifier), \['site' => $siteIdentifier\]);

        -   *param $routeIdentifier:* The route identifier for the shortcut
        -   *param $displayName:* The display name shown in the bookmark list
        -   *param $arguments:* Optional arguments to include in the shortcut URL, default: \[\]

    -   **disableAutomaticReloadButton()**

        Disables the automatic reload button for this module.

        Use this if your module needs custom reload behavior or should not
        have a reload button at all.

    -   **disableAutomaticShortcutButton()**

        Disables the automatic shortcut button for this module.

        Use this if your module should not have a shortcut button.

    -   **docHeaderContent(?\\Psr\\Http\\Message\\ServerRequestInterface $request)**

        Returns the complete document header content as an array for rendering.

        This method aggregates all components (buttons, breadcrumbs) into
        a structured array that can be consumed by the Fluid template rendering
        the backend module layout.

        The returned array structure:
        \- 'enabled': Whether the document header should be rendered
        \- 'buttons': Array of button configurations from the button bar
        \- 'breadcrumb': Breadcrumb trail data from the breadcrumb context
        \- 'languageSelector': Language Selector

        -   *param $request:* the request

        *Returns:* `array`

## Setting the breadcrumb of a backend module {#docheadercomponent-breadcrumb}

<!-- TODO: no Markdown rendering for "versionadded" -->

See Feature: #107794 - Improved breadcrumb navigation in backend.

The breadcrumb shows where the user is, and each of its nodes links back to
that level. A module tells the
`\TYPO3\CMS\Backend\Template\Components\DocHeaderComponent`
what the user is working on:

-   **`setPageBreadcrumb(array $pageRecord)`**

    The page of the given page record, with the path through the page tree.

-   **`setRecordBreadcrumb(string $table, int $uid)`**

    A record of any table, on the page it belongs to.

-   **`setResourceBreadcrumb(ResourceInterface $resource)`**

    A file or folder, with the path through its file storage.

-   **`addBreadcrumbSuffixNode(BreadcrumbNode $node)`**

    An additional node at the end, for example for the current action. A
    node without a URL is not clickable, which suits the current item.

The nodes are built from the current request, so they keep the module and
its current action.

## Layout of the backend module header {#docheadercomponent-layout}

<!-- TODO: no Markdown rendering for "versionchanged" -->

See Feature: #107875 - Improved DocHeader layout and unified language selector.

The module header consists of two rows:

-   The top row has the breadcrumb on the left and, if the module provides
    one, a language selector on the right.
-   The second row is the button bar. On the left, it starts with the
    dropdown of the module actions from button group 0, followed by the
    module buttons. The functional buttons are on the right, such as
    **Reload** or **Bookmark**.

    ![](../../../Images/ManualScreenshots/Backend/DocHeaderComponent.png)

## Adding module actions and a language selector to the module header {#docheadercomponent-language-selector}

`makeDocHeaderModuleMenu()` of
`\TYPO3\CMS\Backend\Template\ModuleTemplate` adds a dropdown
consisting of the submodules of the current module. If there is only one, it is
hidden.

`setLanguageSelector()` of
`\TYPO3\CMS\Backend\Template\Components\DocHeaderComponent`
places a dropdown in the top right corner. If
`setShowActiveLabelText(true)`, the dropdown shows the selected item,
for example "English", as its text, and screen readers announce the label
and the selected item, "Language: English":

**EXT:my_extension/Classes/Controller/ConferenceController.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Routing\UriBuilder;
use TYPO3\CMS\Backend\Template\Components\ComponentFactory;
use TYPO3\CMS\Backend\Template\ModuleTemplate;
use TYPO3\CMS\Backend\Template\ModuleTemplateFactory;
use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
use TYPO3\CMS\Core\Imaging\IconFactory;
use TYPO3\CMS\Core\Site\Entity\Site;

final readonly class ConferenceController
{
  public function __construct(
    private ModuleTemplateFactory $moduleTemplateFactory,
    private ComponentFactory $componentFactory,
    private IconFactory $iconFactory,
    private UriBuilder $uriBuilder,
  ) {}

  public function handleRequest(
    ServerRequestInterface $request,
  ): ResponseInterface {
    $view = $this->moduleTemplateFactory->create($request);
    $pageId = (int)($request->getQueryParams()['id'] ?? 0);
    $languageId = (int)($request->getQueryParams()['language'] ?? 0);

    // Dropdown of the module's submodules, shown if there are several
    $view->makeDocHeaderModuleMenu(['id' => $pageId]);

    $this->addLanguageSelector($view, $request, $pageId, $languageId);

    return $view->renderResponse('Conference/Index');
  }

  private function addLanguageSelector(
    ModuleTemplate $view,
    ServerRequestInterface $request,
    int $pageId,
    int $activeLanguageId,
  ): void {
    /** @var Site $site */
    $site = $request->getAttribute('site');
    $languageSelector = $this->componentFactory->createDropDownButton()
        ->setLabel('Language')
        ->setShowLabelText(true)
        // Show the selected language as the button text
        ->setShowActiveLabelText(true);

    $languages = $site->getAvailableLanguages(
      $this->getBackendUser(),
      false,
      $pageId,
    );
    foreach ($languages as $language) {
      $url = $this->uriBuilder->buildUriFromRoute(
        'my_extension_conference',
        ['id' => $pageId, 'language' => $language->getLanguageId()],
      );
      $languageSelector->addItem(
        $this->componentFactory->createDropDownRadio()
            ->setHref((string)$url)
            ->setLabel($language->getTitle())
            ->setIcon(
              $this->iconFactory->getIcon($language->getFlagIdentifier()),
            )
            ->setActive($language->getLanguageId() === $activeLanguageId),
      );
    }

    $view->getDocHeaderComponent()->setLanguageSelector($languageSelector);
  }

  private function getBackendUser(): BackendUserAuthentication
  {
    return $GLOBALS['BE_USER'];
  }
}

```

## Example: build a module header with buttons and a menu {#docheadercomponent-example}

The following example is extracted from the example Extbase extension
[`t3docs/blog-example`](https://packagist.org/packages/t3docs/blog-example). See the complete source code at
[t3doc/blog-example (GitHub)](https://github.com/TYPO3-Documentation/blog_example).

We use the DocHeaderComponent to register buttons and a menu to the module
header.

**Class T3docs\\BlogExample\\Controller\\BackendController**

```php
<?php

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Template\ModuleTemplate;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class BackendController extends ActionController
{
  private function modifyDocHeaderComponent(
    ModuleTemplate $view,
    string &$context,
  ): void {
    $menu = $this->buildMenu($view, $context);
    $view->getDocHeaderComponent()->getMenuRegistry()->addMenu($menu);

    $buttonBar = $view->getDocHeaderComponent()->getButtonBar();
    $this->addButtons($buttonBar);

    $pageRecord = $this->getPageRecord();
    if (is_array($pageRecord)) {
      $view->getDocHeaderComponent()->setPageBreadcrumb($pageRecord);
    }
  }

  protected function initializeModuleTemplate(
    ServerRequestInterface $request,
  ): ModuleTemplate {
    $view = $this->moduleTemplateFactory->create($request);

    $context = '';
    $this->modifyDocHeaderComponent($view, $context);
    $view->setFlashMessageQueue($this->getFlashMessageQueue());
    $title = $this->getLanguageService()
        ->sL('blog_example.module.mod:mlang_tabs_tab');
    $view->setTitle($title, $context);

    return $view;
  }
}

```