Button components

The button components are used in the DocHeader of a backend module.

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

Changed in version 14.0

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

Deprecated since version 14.0

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

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 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

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

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

$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

New in version 14.0 Feature: #107823 - ComponentFactory for backend components

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

$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

New in version 13.4 Important: #107681 - Disabled state for ShortcutButton and DropDownButton

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 AbstractButton, and DropDownButton implements them as well. The generic button has no disabled state.

EXT:my_extension/Classes/Controller/MyBackendController.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

The backend module 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.

`DropDownButton`

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 it will use the icon of the first active item of this type.

Example:

EXT:my_extension/Classes/Controller/MyBackendController.php

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

`DropDownDivider`

This dropdown item type renders the divider element.

Example:

EXT:my_extension/Classes/Controller/MyBackendController.php

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

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

`DropDownHeader`

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

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

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

`DropDownItem`

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

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`

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

$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`

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

$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);