Action Containers

• Apr 01, 2026
• 6 minutes to read

Action Containers are UI placeholders that display Actions (commands and buttons) in an XAF application. They determine where actions appear, such as toolbars, menus, ribbons, and context menus. Templates control where containers appear on screen.

Common Tasks with Action Containers

You interact with Action Containers when you want to reorganize your application’s command UI, create custom toolbars, or control where specific actions appear:

• Move an Action to a Different Toolbar or Menu
• Group Actions in a Drop-Down Menu (ASP.NET Core Blazor)
• Add a Grid Column with an Action (ASP.NET Core Blazor)
• Create a Custom Action Container
• Reorder Actions in an Action Container

How Action Containers Work

XAF creates Action Containers automatically when it initializes a Template. The process consists of the following steps:

1. Template initialization. XAF creates all Action Containers defined in the Template.
2. Action mapping. The built-in FillActionContainersController reads the ActionDesign | ActionToContainerMapping node in the Application Model to determine which Actions belong in each container.
3. Control creation. The Controller calls each container’s Register method to create platform-specific controls for Actions.

Example (Windows Forms):

• SimpleAction creates a BarButtonItem button control
• SingleChoiceAction creates a BarEditItem dropdown control

ASP.NET Core Blazor Action Containers

The following images show Action Container placement in ASP.NET Core Blazor application UI:

Tip

For more information about Actions in grid columns in ASP.NET Core Blazor applications, refer to the following topic: How to: Add a Grid Column with an Action (ASP.NET Core Blazor).

Customize Action Containers in the Application Model

When to use: Move Actions between existing containers (toolbars/menus) or delete Actions at design time or runtime.

For a detailed scenario, refer to the following topic: How to: Place an Action in a Different Location.

For more information about this Application Model node, refer to the IModelActions interface description.

Customize Action Containers in Code

When to use: Apply conditional logic or dynamic behavior that cannot be configured in the Application Model.

API	Use
Frame.ProcessActionContainer	Use event’s properties to customize Action Container
IActionContainer.Actions	Access Actions of a particular Action Container and customize these Actions. For example, you can toggle an Action’s ActionBase.Active property to deactivate this Action. You can also access an Action’s control and customize it.
ActionBase.CustomizeControl	Customize an Action Control. For a detailed scenario, refer to the following topic: How to: Customize Action Controls
ActionControlsSiteController.CustomizeContainerActions	Customize the action-to-container mapping in code.

Group Actions in a Drop-Down Menu (ASP.NET Core Blazor)

When to use:

• Group Actions in a drop-down menu
• Display the root item as a split button (specify one of included Actions as default)
• Enable a traditional sub-menu UI (specify a caption and/or image for the root item)

Important

Drop-down menus do not support ParametrizedAction and SingleChoiceAction when ItemType is set to SingleChoiceActionItemType.ItemIsMode.

Action Container Properties

Property	Description
isDropDown	Specifies whether the container’s Actions are grouped into a drop-down list.
defaultActionId	Specifies the root menu Action’s identifier.
autoChangeDefaultAction	Specifies whether the last executed Action becomes the default one.
imageName	Specifies the image used as the root menu item.
caption	Specifies the caption used as the root menu item.

Tip

• Image and caption are not mutually exclusive. You can use both as the root item at the same time.
• If you omit defaultActionId, imageName, and caption parameters, XAF displays the first Action as the root item.
• If you specify a SingleChoiceAction as default, it is displayed in the main menu without child items.

Drop-Down Menu in Main Toolbar

1. Create a custom Blazor application template.
2. Specify the Action Container properties.

The following code snippet demonstrates the recommended approach (using an Action as the root item). Two alternative approaches are shown as comments.

File: MySolution.Blazor.Server/Templates/CustomApplicationWindowTemplate.cs

using DevExpress.Blazor;
using DevExpress.ExpressApp.Blazor.Templates;
namespace MySolution.Blazor.Server {
    public class CustomApplicationWindowTemplate : ApplicationWindowTemplate {
        public CustomApplicationWindowTemplate() {
            // Action as the root item
            Toolbar.AddActionContainer("SaveOptions", alignment: ToolbarItemAlignment.Right, isDropDown: true, defaultActionId: "SaveAndNew", autoChangeDefaultAction: true);
            // Image as the root item
            // Toolbar.AddActionContainer("SaveOptions", alignment: ToolbarItemAlignment.Right, isDropDown: true, imageName: "Save");
            // Caption as the root item
            // Toolbar.AddActionContainer("SaveOptions", alignment: ToolbarItemAlignment.Right, isDropDown: true, caption: "Save Options");
        }
    }
}

Drop-Down Menu in Ribbon UI

1. Under the MySolution.Blazor.Server project, add a Window Controller to the Controllers folder.
2. Override the OnActivated method to access the BlazorRibbonController and subscribe to its RibbonActionContainerCreating event. This event fires when the controller generates a DxRibbon Action Container model.
3. Specify the Action Container properties.

The following code snippet:

• Groups the Actions in the SaveOptions Container in a drop-down menu
• Sets the default Action to SaveAndClose

• Sets the last executed Action as the default

  File: MySolution.Blazor.Server\Controllers\CustomizeRibbonActionContainerController.cs

  using DevExpress.ExpressApp;
  using DevExpress.ExpressApp.Blazor.SystemModule;
  
  namespace MySolution.Blazor.Server.Controllers;
  
  public class CustomizeRibbonActionContainerController : WindowController {
      protected override void OnActivated() {
          base.OnActivated();
          var controller = Frame.GetController<BlazorRibbonController>();
          if(controller != null) {
              controller.RibbonActionContainerCreating += Controller_RibbonActionContainerCreating;
          }
      }
      private void Controller_RibbonActionContainerCreating(object sender, RibbonActionContainerCreatingEventArgs e) {
          if(e.ActionContainer.ContainerId == "SaveOptions") {
              e.ActionContainer.IsDropDown = true;
              e.ActionContainer.DefaultActionId = "SaveAndClose";
              e.ActionContainer.AutoChangeDefaultAction = true;
          }
      }
      protected override void OnDeactivated() {
          var controller = Frame.GetController<BlazorRibbonController>();
          if(controller != null) {
              controller.RibbonActionContainerCreating -= Controller_RibbonActionContainerCreating;
          }
          base.OnDeactivated();
      }
  }
  

Implement a Custom Action Container

When to use: Replace the default controls with custom UI components (advanced scenario).

1. Inherit from the desired platform control and implement the IActionContainer interface. Alternatively, you can inherit your custom container from one of the existing Action Containers. You may also need to specify the controls XAF should use for each Action type.

2. After you declared your own Action Container, create a new Template or customize an existing template as described in the following topics:

   • How To: Create a Custom Blazor Application Template
   • How to: Create a Custom WinForms Standard Template
   • How to: Create a Custom WinForms Ribbon Template

3. Add your Action Container to the Template and add your Action Container’s instance to the list returned by the Template’s IFrameTemplate.GetContainers method.

Tip

If you have XAF sources installed, you can see how built-in Action Containers are implemented in the following locations:

• %PROGRAMFILES%\DevExpress 25.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Web\Templates\ActionContainers\
• %PROGRAMFILES%\DevExpress 25.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Win\Templates\ActionContainers\
• %PROGRAMFILES%\DevExpress 25.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Blazor\Templates\

API Reference

API	Description
Category	Specifies the Action Container where XAF displays the current Action.
ContextMenuTemplate	Offers access to a List Editor’s Context Menu Template.
CustomizeContainerActions	Fires when Actions are added to the Action Containers.