---
title: "Button components"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:button-components@main"
source: "ApiOverview/Backend/ButtonComponents.rst"
rendered: "2026-10-04T09:53:59+00:00"
---

# Button components {#button-components}

The button components are used in the
[DocHeader](https://docs.typo3.org/permalink/t3coreapi:backend-modules-template-without-extbase-docheader@main) of a
[backend module](https://docs.typo3.org/permalink/t3coreapi:backend-modules@main).

Create the components with the
`\TYPO3\CMS\Backend\Template\Components\ComponentFactory`, which
provides a `create*()` method for every button, dropdown item and menu
component:

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

The ComponentFactory
creates all backend components, see
Feature: #107823 - ComponentFactory for backend components.

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

The make*() methods of
\TYPO3\CMS\Backend\Template\Components\ButtonBar have been
deprecated and are removed with TYPO3 v15. Use the create*() methods of
the ComponentFactory
instead, see
Deprecation: #107823 - ButtonBar, Menu, and MenuRegistry make* methods deprecated.

Example on how to use a button component:

**EXT:my_extension/Classes/Controller/MyBackendController.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\Template\Components\ButtonBar;
use TYPO3\CMS\Backend\Template\Components\ComponentFactory;
use TYPO3\CMS\Backend\Template\ModuleTemplate;
use TYPO3\CMS\Backend\Template\ModuleTemplateFactory;
use TYPO3\CMS\Core\Imaging\IconFactory;

final class MyBackendController
{
  private ModuleTemplate $moduleTemplate;

  public function __construct(
    protected readonly ModuleTemplateFactory $moduleTemplateFactory,
    protected readonly IconFactory $iconFactory,
    protected readonly ComponentFactory $componentFactory,
    // ...
  ) {}

  public function handleRequest(ServerRequestInterface $request): ResponseInterface
  {
    $this->moduleTemplate = $this->moduleTemplateFactory->create($request);
    $this->setDocHeader();
    // ... some more logic
  }

  private function setDocHeader(): void
  {
    $buttonBar = $this->moduleTemplate->getDocHeaderComponent()->getButtonBar();
    $dropDownButton = $this->componentFactory->createDropDownButton()
        ->setLabel('Dropdown')
        ->setTitle('Save')
        ->setIcon($this->iconFactory->getIcon('actions-heart'))
        ->addItem(
          $this->componentFactory->createDropDownItem()
                ->setLabel('Item')
                ->setHref('#'),
        );
    $buttonBar->addButton(
      $dropDownButton,
      ButtonBar::BUTTON_POSITION_RIGHT,
      2,
    );
  }
}

```

With the `\TYPO3\CMS\Backend\Template\ModuleTemplate` of the
module at hand, its method `addButtonToButtonBar()` adds a button in one
step. It takes the same position and group as `addButton()`:

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

```php
$this->moduleTemplate->addButtonToButtonBar(
  $dropDownButton,
  ButtonBar::BUTTON_POSITION_RIGHT,
  2,
);
```

> [!NOTE]
> **See also**
>
> -   [ModifyButtonBarEvent](https://docs.typo3.org/permalink/t3coreapi:modifybuttonbarevent@main)

**Table of contents**

-   [Generic button component](https://docs.typo3.org/permalink/t3coreapi:generic-button-component-1@main)
-   [Setting HTML attributes on backend buttons](https://docs.typo3.org/permalink/t3coreapi:setting-html-attributes-on-backend-buttons@main)
-   [Disabling a backend button](https://docs.typo3.org/permalink/t3coreapi:disabling-a-backend-button@main)
-   [Dropdown button components](https://docs.typo3.org/permalink/t3coreapi:dropdown-button-components-1@main)

## Generic button component {#generic-button-component}

The component `\TYPO3\CMS\Backend\Template\Components\Buttons\GenericButton`
allows to render any markup in the module menu bar.

Example:

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

```php
$buttonBar = $this->moduleTemplate->getDocHeaderComponent()->getButtonBar();
$genericButton = GeneralUtility::makeInstance(GenericButton::class)
    ->setTag('a')
    ->setHref('#')
    ->setLabel('My label')
    ->setTitle('My title')
    ->setIcon($this->iconFactory->getIcon('actions-heart'))
    ->setAttributes(['data-value' => '123']);
$buttonBar->addButton($genericButton, ButtonBar::BUTTON_POSITION_RIGHT, 2);
```

## Setting HTML attributes on backend buttons {#button-components-attributes}

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

The link, input and split buttons accept HTML attributes through
`setAttributes()`, like the generic button does. Use these buttons
rather than a generic button if you only need a few attributes:

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

```php
$previewButton = $this->componentFactory->createLinkButton()
    ->setHref($previewUrl)
    ->setTitle('Open preview')
    ->setIcon($this->iconFactory->getIcon('actions-view'))
    ->setAttributes(['target' => '_blank', 'rel' => 'noopener']);
$buttonBar->addButton($previewButton, ButtonBar::BUTTON_POSITION_RIGHT, 2);
```

## Disabling a backend button {#button-components-disabled}

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

An action that is not available right now reads better as a disabled
button than as a missing one: the button bar keeps its layout, and the
user still sees that the action exists.

`setDisabled()` sets the state and `isDisabled()` reads it back. The
link, input and split buttons inherit both from
`\TYPO3\CMS\Backend\Template\Components\Buttons\AbstractButton`,
and
`\TYPO3\CMS\Backend\Template\Components\Buttons\DropDownButton`
implements them as well. The generic button has no disabled state.

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

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Repository\ItemRepository;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Routing\UriBuilder;
use TYPO3\CMS\Backend\Template\Components\ButtonBar;
use TYPO3\CMS\Backend\Template\Components\Buttons\DropDown\DropDownItem;
use TYPO3\CMS\Backend\Template\Components\ComponentFactory;
use TYPO3\CMS\Backend\Template\ModuleTemplate;
use TYPO3\CMS\Backend\Template\ModuleTemplateFactory;
use TYPO3\CMS\Core\Imaging\IconFactory;

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

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

    $this->addExportButton($view, $pageId);

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

  private function addExportButton(
    ModuleTemplate $view,
    int $pageId,
  ): void {
    $exportButton = $this->componentFactory->createDropDownButton()
        ->setLabel('Export')
        ->setIcon($this->iconFactory->getIcon('actions-download'))
        // Nothing to export yet: keep the button, but switch it off
        ->setDisabled($this->itemRepository->countByPid($pageId) === 0)
        ->addItem($this->exportItem('CSV', $pageId, 'csv'))
        ->addItem($this->exportItem('XML', $pageId, 'xml'));

    $view->addButtonToButtonBar(
      $exportButton,
      ButtonBar::BUTTON_POSITION_RIGHT,
      2,
    );
  }

  private function exportItem(
    string $label,
    int $pageId,
    string $format,
  ): DropDownItem {
    $url = $this->uriBuilder->buildUriFromRoute(
      'my_extension_export',
      ['id' => $pageId, 'format' => $format],
    );

    return $this->componentFactory->createDropDownItem()
        ->setLabel($label)
        ->setHref((string)$url);
  }
}

```

## Dropdown button components {#dropdown-button-components}

The [backend module](https://docs.typo3.org/permalink/t3coreapi:backend-modules@main) menu button bar can display
dropdowns. This enables interface interactions, such as switching the current
view from list to tiles, or group actions like clipboard and thumbnail
visibility. This helps unclutter the views and allow the user to see more
information at a glance.

Each dropdown consists of various elements ranging from headings to item links
that can display the current status. The button automatically changes the
icon representation to the icon of the the first active radio icon in the
dropdown list.

![DropDown button component in the :guilabel:\`Media\` module](../../Images/ManualScreenshots/Backend/FileModuleDropDownButton.png)

### `DropDownButton` {#dropdown-button-components-button}

This button type is a container for dropdown items. It will render a dropdown
containing all items attached to it. There are different kinds available, each
item needs to implement the
`\TYPO3\CMS\Backend\Template\Components\Buttons\DropDown\DropDownItemInterface`.
When this type contains elements of type
[DropDownRadio](https://docs.typo3.org/permalink/t3coreapi:dropdown-button-components-radio@main) it will use the icon of
the first active item of this type.

Example:

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

```php
$dropDownButton = $this->componentFactory->createDropDownButton()
    ->setLabel('Dropdown')
    ->setTitle('Save')
    ->setIcon($this->iconFactory->getIcon('actions-heart'))
    ->addItem(
        $this->componentFactory->createDropDownItem()
            ->setLabel('Item')
            ->setHref('#')
    );
```

### `DropDownDivider` {#dropdown-button-components-divider}

This dropdown item type renders the divider element.

Example:

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

```php
use TYPO3\CMS\Backend\Template\Components\Buttons\DropDown\DropDownDivider;

$item = GeneralUtility::makeInstance(DropDownDivider::class);
$dropDownButton->addItem($item);
```

### `DropDownHeader` {#dropdown-button-components-header}

This dropdown item type renders a non-interactive text element to group items
and gives more meaning to a set of options.

Example:

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

```php
use TYPO3\CMS\Backend\Template\Components\Buttons\DropDown\DropDownHeader;

$item = GeneralUtility::makeInstance(DropDownHeader::class)
    ->setLabel('My label');
$dropDownButton->addItem($item);
```

### `DropDownItem` {#dropdown-button-components-item}

This dropdown item type renders a simple element. Use this element if you need
a link button.

Example:

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

```php
use TYPO3\CMS\Backend\Template\Components\Buttons\DropDown\DropDownItem;

$item = GeneralUtility::makeInstance(DropDownItem::class)
    ->setTag('a')
    ->setHref('#')
    ->setLabel('My label')
    ->setTitle('My title')
    ->setIcon($this->iconFactory->getIcon('actions-heart'))
    ->setAttributes(['data-value' => '123']);
$dropDownButton->addItem($item);
```

### `DropDownRadio` {#dropdown-button-components-radio}

This dropdown item type renders an element with an active state. Use this
element to display a radio-like selection of a state. When set to active, it
will show a dot in front of the icon and text to indicate that this is the
current selection.

At least two of these items need to exist within a dropdown button, so a user
has a choice of a state to select.

Example:

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

```php
$item = GeneralUtility::makeInstance(DropDownRadio::class)
    ->setHref('#')
    ->setActive(true)
    ->setLabel('My label')
    ->setTitle('My title')
    ->setIcon($this->iconFactory->getIcon('actions-viewmode-list'))
    ->setAttributes(['data-type' => 'list']);
$dropDownButton->addItem($item);

$item = GeneralUtility::makeInstance(DropDownRadio::class)
    ->setHref('#')
    ->setActive(false)
    ->setLabel('Tiles')
    ->setTitle('Tiles')
    ->setIcon($this->iconFactory->getIcon('actions-viewmode-tiles'))
    ->setAttributes(['data-type' => 'tiles']);
$dropDownButton->addItem($item);
```

### `DropDownToggle` {#dropdown-button-components-toggle}

This dropdown item type renders an element with an active state. When set to
active, it will show a checkmark in front of the icon and text to indicate the
current state.

Example:

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

```php
$item = GeneralUtility::makeInstance(DropDownToggle::class)
    ->setHref('#')
    ->setActive(true)
    ->setLabel('My label')
    ->setTitle('My title')
    ->setIcon($this->iconFactory->getIcon('actions-heart'))
    ->setAttributes(['data-value' => '123']);
$dropDownButton->addItem($item);
```