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.v24.2.dll
NuGet Package: DevExpress.Blazor
Declaration
public class DxSplitButton :
DxDropDownButtonBaseRemarks
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.
Add a Split Button to a Project
Follow the steps below to add a Split Button component to an application:
- 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.
- Add the following markup to a
.razorfile:<DxSplitButton>…</DxSplitButton>. - Specify the drop-down window’s content. You can populate the window with a list of commands or display custom content.
- Customize component appearance.
- Optional. Specify the primary button text or change the secondary button position.
.NET 8 and .NET 9 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.
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.
<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:
<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.
<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.
@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.
@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";
}
}
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.
<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:
<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.
<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.
<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>
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
DropDowndisplay 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:
<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>
Tooltips
Use the Tooltip property to specify tooltip text for the split button or a drop-down list item.
<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.
The following shortcut keys are available:
| Shortcut Keys | Description |
|---|---|
| Tab, Shift+Tab | When the Split Button is focused, moves focus to the next/previous focusable element on a page. |
| Enter, Space Alt+Down Arrow |
Opens a drop-down window and moves focus to its first item. |
| Right Arrow | For drop-down list items: Opens a drop-down window and moves focus to its first item. |
| Alt+Up Arrow | Closes all drop-down windows and moves focus to the main button. |
| Esc | Closes the current drop-down window and moves focus to the corresponding root item (or main button). |
| Left Arrow | For drop-down list items: Closes the current drop-down window and moves focus to the corresponding root item. |
| Right Arrow Left Arrow |
Moves focus between primary and secondary buttons. |
| Down Arrow | Moves focus to the next drop-down list item. |
| Up Arrow | Moves focus to the previous drop-down list item. |
Troubleshooting
If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.