DxSplitButton Class

A composite control that consists of a primary button and a toggleable secondary button that reveals a drop-down element.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v25.1.dll

NuGet Package: DevExpress.Blazor

Declaration

C#

public class DxSplitButton :
    DxDropDownButtonBase

Remarks

The DevExpress Split Button component for Blazor (<DxSplitButton>) allows users to execute a default action (primary button click) and display a drop-down (secondary button click). The drop-down displays either a command list or custom content. You can apply a predefined style to the component and customize its layout and appearance.

Run Demo: Split Button

Add a Split Button to a Project

Follow the steps below to add a Split Button component to an application:

1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
2. Add the following markup to a .razor file: <DxSplitButton>…</DxSplitButton>.
3. Specify the drop-down window’s content. You can populate the window with a list of commands or display custom content.
4. Customize component appearance.
5. Optional. Specify the primary button text or change the secondary button position.

API Reference

Refer to the following list for the component API reference: DxSplitButton Members.

Static Render Mode Specifics

Blazor Split Button does not support static render mode. Enable interactivity to use the component in your application. Refer to the following topic for more details: Enable Interactive Render Mode.

Drop-Down List

The <DxSplitButton> component operates in unbound mode and requires that you add DxDropDownButtonItem objects to the component markup. Use the Items property to specify a collection of root items. Each item can have a collection of child items.

When a user clicks a drop-down list item, the drop-down menu closes. To change this behavior, set the CloseDropDownOnItemClick property to false.

Run Demo: Split Button

Item Groups

You can display horizontal lines within the menu to separate items into groups. To start a new group, set the item’s BeginGroup property to true.

Razor

<DxSplitButton RenderStyle="ButtonRenderStyle.Secondary"
               Text="Clipboard"
               IconCssClass="tb-icon tb-icon-paste"
               CssClass="me-1">
    <Items>
        <DxDropDownButtonItem Text="Cut" IconCssClass="menu-icon-cut menu-icon" />
        <DxDropDownButtonItem Text="Copy" IconCssClass="menu-icon-copy menu-icon" />
        <DxDropDownButtonItem Text="Paste" IconCssClass="tb-icon tb-icon-paste" />
        <DxDropDownButtonItem Text="Paste Special" BeginGroup="true">
            <Items>
                <DxDropDownButtonItem Text="Paste Text Only" />
                <DxDropDownButtonItem Text="Paste Picture" Enabled="false" />
                <DxDropDownButtonItem Text="Paste as Hyperlink" />
            </Items>
        </DxDropDownButtonItem>
    </Items>
</DxSplitButton>

Items with Hyperlinks

Use the NavigateUrl property to specify a URL where the web browser navigates when the drop-down list item is clicked. To specify where the browser should open the URL (for example, the current window or a new tab), use the Target property.

The following code snippet opens the Documentation item’s NavigateUrl link in the same tab and the Demos item’s link in a new tab:

Razor

<DxSplitButton Text="Blazor Components"
               RenderStyleMode="ButtonRenderStyleMode.Outline" >
    <Items>
        <DxDropDownButtonItem Text="Documentation"
                              NavigateUrl="https://docs.devexpress.com/Blazor/400725/blazor-components" />
        <DxDropDownButtonItem Text="Demos"
                              NavigateUrl="https://demos.devexpress.com/blazor/"
                              Target="_blanc" />
    </Items>
</DxSplitButton>

Items with Custom Drop-Down Content

Use the item’s DropDownContentTemplate property to display custom content within the item’s drop-down window.

Razor

<DxSplitButton Text="Blazor Components"
               RenderStyle="ButtonRenderStyle.Secondary">
    <Items>
        <DxDropDownButtonItem Text="Documentation" />
        <DxDropDownButtonItem Text="Demos" />
        <DxDropDownButtonItem Text="Click to search">
            <DropDownContentTemplate>
                <div class="d-flex flex-row align-items-center h-100">
                    <DxSearchBox CssClass="search py-0" aria-label="Search" />
                </div>
            </DropDownContentTemplate>
        </DxDropDownButtonItem>
    </Items>
</DxSplitButton>

Click Events

Use the component’s ItemClick event to specify a common click handler for all drop-down list items. To react to an individual item click, handle the item’s Click event.

Razor

@inject IJSRuntime JSRuntime

<p>The clicked item is @ClickedItem</p>

<DxSplitButton RenderStyle="ButtonRenderStyle.Secondary"
               Text="Clipboard"
               IconCssClass="tb-icon tb-icon-paste"
               CssClass="me-1"
               ItemClick="@OnItemCommonClick">
    <Items>
        <DxDropDownButtonItem Text="Cut"
                              IconCssClass="menu-icon-cut menu-icon"
                              Click="@OnCutItemClick" />
        <DxDropDownButtonItem Text="Copy"
                              IconCssClass="menu-icon-copy menu-icon"
                              Click="@OnCopyItemClick" />
        <DxDropDownButtonItem Text="Paste"
                              IconCssClass="tb-icon tb-icon-paste" />
    </Items>
</DxSplitButton>

@code {
    public string ClickedItem { get; set; } = "";

    void OnCutItemClick(MouseEventArgs args) {
        ClickedItem = "Cut";
    }
    void OnCopyItemClick(MouseEventArgs args) {
        ClickedItem = "Copy";
    }

    async Task OnItemCommonClick(DropDownButtonItemClickEventArgs args) {
        await JSRuntime.InvokeVoidAsync("alert", $"The drop-down list item has been clicked.");
    }
}

Custom Drop-Down Window Content

The <DxSplitButton> component can display a drop-down window with custom content. Specify the component’s DropDownContentTemplate property to customize the drop-down window’s layout and appearance.

Razor

@inject NwindDataService NwindDataService
<DxSplitButton RenderStyle="ButtonRenderStyle.Secondary"
               Text="Select Employee"
               CssClass="me-1"
               IconCssClass="sb-icon sb-icon-user-profile"
               DropDownVisible="DropDownVisible">
    <ChildContent>
        <div class="item-template">
            <img src="@StaticAssetUtils.GetImagePath(GetImageFileName(Value))" alt="@Value.FullName"/>
            <span class="item-template-name">@Value.FullName</span>
        </div>
    </ChildContent>
    <DropDownContentTemplate>
        <DxListBox Data="@Data"
                   @bind-Value="@Value"
                   CssClass="cw-640 ch-360">
            <ItemDisplayTemplate>
                <div class="item-template">
                    <img src="@StaticAssetUtils.GetImagePath(GetImageFileName(context.DataItem))"
                         alt="@context.DataItem.FullName"/>
                    <span class="item-template-name">@context.DataItem.FullName</span>
                </div>
            </ItemDisplayTemplate>
        </DxListBox>
    </DropDownContentTemplate>
</DxSplitButton>

@code {
    IEnumerable<Employee> Data { get; set; }
    bool DropDownVisible { get; set; }
    Employee Value { get; set; }
    protected override async Task OnInitializedAsync() {
        Data = await NwindDataService.GetEmployeesAsync();
        Value = Data.FirstOrDefault();
        DropDownVisible = false;
        await base.OnInitializedAsync();
    }
    string GetImageFileName(Employee employee) {
        return $"employees/item-template{employee.EmployeeId}.jpg";
    }
}

Run Demo: Split Button

Primary Button Clicks

Use the <DxSplitButton> component’s Click event to specify a click handler for the primary button. If you use the NavigateUrl property with the Click event’s handler, the browser handles the event first and then navigates to the specified URL.

Razor

<p>@Message</p>
<DxSplitButton Text="Blazor Components"
               RenderStyleMode="ButtonRenderStyleMode.Outline"
               NavigateUrl="https://docs.devexpress.com/Blazor/400725/blazor-components"
               Target="_blanc"
               Click="OnPrimaryButtonClick">
    <Items>
        <DxDropDownButtonItem Text="Demos"
                              NavigateUrl="https://demos.devexpress.com/blazor/" />
    </Items>
</DxSplitButton>

@code {
    public string Message { get; set; }
    void OnPrimaryButtonClick(MouseEventArgs args) {
        Message = "The primary button is clicked.";
    }
}

You can also use the primary button to submit a form. To enable form submit, set the SubmitFormOnClick property to true.

Size Modes

Use the SizeMode property to specify <DxSplitButton> component size. The following code snippet applies different size modes to Split Button components:

Razor

<DxSplitButton Text="Small" SizeMode="SizeMode.Small">
    <Items>
        <DxDropDownButtonItem Text="Favorites" />
        <DxDropDownButtonItem Text="Recently Added" />
        <DxDropDownButtonItem Text="Show All" />
    </Items>
</DxSplitButton>
<DxSplitButton Text="Medium" SizeMode="SizeMode.Medium">
    <Items>
        <DxDropDownButtonItem Text="Favorites" />
        <DxDropDownButtonItem Text="Recently Added" />
        <DxDropDownButtonItem Text="Show All" />
    </Items>
</DxSplitButton>
<DxSplitButton Text="Large" SizeMode="SizeMode.Large">
    <Items>
        <DxDropDownButtonItem Text="Favorites" />
        <DxDropDownButtonItem Text="Recently Added" />
        <DxDropDownButtonItem Text="Show All" />
    </Items>
</DxSplitButton>

Customization

This section describes how you can customize the <DxSplitButton> component and its elements.

Predefined Styles

The <DxSplitButton> component allows you to apply a predefined style to the main button. You can use the following properties:

RenderStyle

Specifies the split button’s predefined style.

RenderStyleMode

Specifies the split button’s color filling type.

Razor

<DxSplitButton RenderStyle="ButtonRenderStyle.Secondary"
               RenderStyleMode="ButtonRenderStyleMode.Contained"
               Text="Primary (Contained)">
    @* ... *@
</DxSplitButton>
<DxSplitButton RenderStyle="ButtonRenderStyle.Danger"
               RenderStyleMode="ButtonRenderStyleMode.Outline"
               Text="Danger (Outline)">
    @* ... *@
</DxSplitButton>
<DxSplitButton RenderStyle="ButtonRenderStyle.Link"
               RenderStyleMode="ButtonRenderStyleMode.Text"
               Text="Link (Text)">
    @* ... *@
</DxSplitButton>

Icons

The <DxSplitButton> component allows you to add icons to the primary button and drop-down list items. The following properties are available:

IconCssClass

Specifies the icon’s CSS class.

IconPosition

Specifies the icon’s position.

Razor

<DxSplitButton RenderStyle="ButtonRenderStyle.Secondary"
               Text="Clipboard"
               IconCssClass="tb-icon tb-icon-paste"
                  CssClass="me-1">
    <Items>
        <DxDropDownButtonItem Text="Cut" IconCssClass="menu-icon-cut menu-icon" />
        <DxDropDownButtonItem Text="Copy" IconCssClass="menu-icon-copy menu-icon" />
        <DxDropDownButtonItem Text="Paste" IconCssClass="tb-icon tb-icon-paste" />
    </Items>
</DxSplitButton>

CSS

.tb-icon-paste {
    -webkit-mask-image: url(../images/paste.svg);
    mask-image: url(../images/paste.svg);
}

.menu-icon-copy {
    mask-image: url(../images/copy.svg);
    -webkit-mask-image: url(../images/copy.svg);
}

.menu-icon-cut {
    mask-image: url(../images/cut.svg);
    -webkit-mask-image: url(../images/cut.svg);
}

.tb-icon {
    width: 1rem;
    height: 1rem;
    background-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    background-position: center center;
    background-color: currentColor;
    opacity: 0.7;
}

.menu-icon {
    width: 1rem;
    height: 1rem;
    min-width: 1rem;
    min-height: 1rem;
    background-size: contain;
    mask-repeat: no-repeat;
    -webkit-mask-repeat: no-repeat;
    background-position: center center;
    background-color: currentColor;
    opacity: 0.7;
}

Drop-Down Elements

The <DxSplitButton> component displays the drop-down toggle icon if a command reveals the drop-down element. You can use the DropDownToggleCssClass property to customize toggle appearance. To hide the toggle icon, set the DropDownToggleVisible property to false.

You can also configure settings of drop-down elements. The following properties are available:

DropDownCssClass

Assigns a CSS class to the drop-down element

DropDownPosition

Specifies the drop-down element’s position relative to the target element.

DropDownDisplayMode

Specifies how the Split Button component displays its drop-down elements.

OpenDropDownOnItemClick

Specifies whether to open a drop-down element on item click in DropDown display mode on desktop devices.

The following code snippet changes the position of the main drop-down element in the <DxSplitButton> component and customizes the drop-down toggle icon:

Razor

<DxSplitButton Text="Blazor Components"
               RenderStyleMode="ButtonRenderStyleMode.Outline"
               DropDownToggleCssClass="toggle-icon"
               DropDownPosition="DropDownPosition.Right">
    <Items>
        <DxDropDownButtonItem Text="Documentation"
                              NavigateUrl="https://docs.devexpress.com/Blazor/400725/blazor-components" />
        <DxDropDownButtonItem Text="Demos"
                              NavigateUrl="https://demos.devexpress.com/blazor/" />
    </Items>
</DxSplitButton>

CSS

.toggle-icon {
    width: 1rem;
    height: 1rem;
    background-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    background-position: center center;
    background-color: currentColor;
    opacity: 0.7;
    -webkit-mask-image: url(../images/arrow.svg);
    mask-image: url(../images/arrow.svg);
}

Tooltips

Use the Tooltip property to specify tooltip text for the split button or a drop-down list item.

Razor

<DxSplitButton Text="Blazor Components"
               RenderStyleMode="ButtonRenderStyleMode.Outline"
               Tooltip="Click to see possible options">
    <Items>
        <DxDropDownButtonItem Text="Documentation"
                              NavigateUrl="https://docs.devexpress.com/Blazor/400725/blazor-components"
                              Tooltip="This item contains a link" />
        <DxDropDownButtonItem Text="Demos"
                              NavigateUrl="https://demos.devexpress.com/blazor/"
                              Tooltip="This item contains a link" />
    </Items>
</DxSplitButton>

Keyboard Navigation

The DevExpress Blazor Split Button component supports keyboard shortcuts that allow users to access a drop-down element and navigate through drop-down list items.

Note

Keyboard support allows users who cannot use a mouse or rely on assistive technologies (like screen readers or switch devices) to interact with application content. Refer to the Accessibility help topic for information on other accessibility areas that we address.

The following shortcut keys are available:

Shortcut Keys	Description
Tab	When the primary button is focused, moves focus to the secondary button. From the secondary button, moves focus to the next page element.
Shift+Tab	When the secondary button is focused, moves focus to the primary button. From the primary button, moves focus to the previous page element.
Enter Space Alt+Down Arrow	Opens a drop-down window and moves focus to its first item.
Esc	Closes the current drop-down window and moves focus to the corresponding root item (or main button).
Alt+Up Arrow	Closes all drop-down windows and moves focus to the main button.
Down Arrow	In drop-down list: Cycles focus forward through the items.
Up Arrow	In drop-down list: Cycles focus backward through the items.
Right Arrow	For multi-level list items: Opens a nested drop-down window and moves focus to its first item.
Left Arrow	For multi-level list items: Closes the nested drop-down window and moves focus to the corresponding root item.

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Implements

IComponent

IHandleEvent

IHandleAfterRender

IDisposable

Inheritance

Object

ComponentBase

DxComponentBase

DxButtonBase

DxDropDownButtonBase

DxSplitButton