The ButtonBar organizes buttons into two positions (left and right) with multiple groups, allowing precise control over button placement and visual grouping.

Buttons are organized in a three-level structure:

1. Position: LEFT or RIGHT side of the header
2. Group: Numerical groups within each position (1, 2, 3, etc.)
3. Individual buttons within each group

Groups are rendered with visual spacing between them, allowing logical grouping of related actions. Lower group numbers appear first (left-to-right, or top-to-bottom on mobile).

Example - Using pre-configured buttons from ComponentFactory:

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

public function myAction(): ResponseInterface
{
    $buttonBar = $this->moduleTemplate->getDocHeaderComponent()->getButtonBar();

    // Use pre-configured save button
    $saveButton = $this->componentFactory->createSaveButton('editform');
    $buttonBar->addButton($saveButton, ButtonBar::BUTTON_POSITION_LEFT, 1);

    // Use pre-configured back button
    $backButton = $this->componentFactory->createBackButton($returnUrl);
    $buttonBar->addButton($backButton, ButtonBar::BUTTON_POSITION_LEFT, 2);
}

Example - Creating custom buttons with ComponentFactory:

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

public function myAction(): ResponseInterface
{
    $buttonBar = $this->moduleTemplate->getDocHeaderComponent()->getButtonBar();

    // Create custom link button
    $customButton = $this->componentFactory->createLinkButton()
        ->setHref('/custom-action')
        ->setTitle('Custom Action')
        ->setIcon($iconFactory->getIcon('actions-custom'));
    $buttonBar->addButton($customButton, ButtonBar::BUTTON_POSITION_LEFT, 1);
}

Example - Buttons with automatic positioning:

// ShortcutButton implements PositionInterface and positions itself automatically
$shortcutButton = $this->componentFactory->createShortcutButton()
    ->setRouteIdentifier('my_module')
    ->setDisplayName('My Module');
$buttonBar->addButton($shortcutButton); // Position and group are automatic

Example - Dropdown button:

$dropdownButton = $this->componentFactory->createDropDownButton()
    ->setLabel('Actions')
    ->setIcon($iconFactory->getIcon('actions-menu'));

$item1 = GeneralUtility::makeInstance(DropDownItem::class)
    ->setLabel('Edit')
    ->setHref('/edit');
$dropdownButton->addItem($item1);

$item2 = GeneralUtility::makeInstance(DropDownItem::class)
    ->setLabel('Delete')
    ->setHref('/delete');
$dropdownButton->addItem($item2);

$buttonBar->addButton($dropdownButton, ButtonBar::BUTTON_POSITION_RIGHT, 1);