DxListBox<TData, TValue> Class
A control that can connect to a data source and display a list of selectable items.
Namespace: DevExpress.Blazor
Assembly:
DevExpress.Blazor.v23.1.dll
NuGet Package:
DevExpress.Blazor
Declaration
public class DxListBox<TData, TValue> :
DxDataEditor<TData>,
IDataSourceSettings<TData>,
IHandleDataLayoutChanged
Type Parameters
Name |
Description |
TData |
The data item type.
|
TValue |
The value type.
|
DevExpress List Box for Blazor (<DxListBox>
) allows you to display a list of selectable items from a data source.

Run Demo: List Box - Overview
Add a List Box to a Project
Follow the steps below to add the List Box 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
<DxListBox>
…</DxListBox>
markup to a .razor
file.
- Bind the component to data.
- Configure the component: handle an item selection, customize item appearance, and so on (see the sections below).
Bind to Data
Use the Data property to bind the List Box to a strongly typed collection. Initialize this collection in the OnInitialized lifecycle method or before this method is invoked. Use the DataAsync property instead of the Data
property if a strongly typed collection is loaded asynchronously (for instance, from an HTTP request).
Use the Value or Values property to select one or multiple List Box items programmatically. You can use the @bind attribute to bind these properties to a data field. Refer to the following topic for more information: Two-Way Data Binding.
<DxListBox Data="@Cities" @bind-Values="@Values"></DxListBox>
@code {
IEnumerable<string> Cities = new List<string>() {
"London",
"Berlin",
"Paris",
};
IEnumerable<string> Values { get; set; }
}
The List Box can detect IQueryable<T> collections and use benefits of the corresponding LINQ query providers (such as Entity Framework).
If a data collection stores custom objects (IEnumerable<CustomType>
), override the object’s Equals method and set the TextFieldName property to specify the field name with item values. Otherwise, the List Box is populated with CustomType.ToString()
values.
@using BlazorApp.Data
<DxListBox Data="@Staff.DataSource"
@bind-Values="@Values"
TextFieldName="@nameof(Person.Text)">
</DxListBox>
@code {
IEnumerable<Person> Values { get; set; } = Staff.DataSource.Take(1);
}
namespace BlazorApp.Data {
public class Person {
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public Department Department { get; set; }
public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
public override bool Equals(object obj) {
if (obj is Person typedObj) {
return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
&& (this.Department == typedObj.Department);
}
return base.Equals(obj);
}
}
public enum Department { Motors, Electronics, Software }
}
using System;
using System.Collections.Generic;
namespace BlazorApp.Data {
public static class Staff {
private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
var dataSource = new List<Person>() {
new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
return dataSource;
});
public static List<Person> DataSource { get { return dataSource.Value; } }
}
}

Run Demo: List Box - Overview
Load Custom Data
When you bind an editor to data from a Web API service, assign the data type to the component’s T
parameter and use the CustomData property to implement custom data load logic.
View Example: Data Editors for Blazor - Custom data binding
You can also enable Virtual Scrolling to improve client-side performance.
Item Selection
Use the SelectionMode property to change the List Box selection mode. The component supports the following selection modes:
- Single (default)
Users can only select one List Box item at a time. A user should click a List Box item to select it.
Use the Value property to access/specify the selected item in code. To respond to selection changes, handle the ValueChanged event.
- Multiple
Users can select multiple items in the List Box. A user should click the initial item, hold the Shift key, and select the final item to specify the range of items. To add/remove individual items to/from the selection, a user should click an item with the Ctrl key pressed. Enable the ShowCheckboxes property to allow users to use checkboxes to select items.
Use the the Values property to access/specify selected items in multiple selection mode. To respond to selection changes, handle the ValuesChanged event.
- None (the selection is disabled)
- Users cannot select List Box items.
The code below enables multiple selection in the List Box and adds checkboxes to the component. Users can click items or corresponding checkboxes to select the nodes.
@using StaffData
<DxListBox Data="@Staff.DataSource"
TextFieldName="@nameof(Person.Text)"
SelectionMode="ListBoxSelectionMode.Multiple"
ShowCheckboxes="true"
@bind-Values="@Values">
</DxListBox>
@code {
IEnumerable<Person> Values { get; set; }
}
namespace StaffData {
public static class Staff {
private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
var dataSource = new List<Person>() {
new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
return dataSource;
});
public static List<Person> DataSource { get { return dataSource.Value; } }
}
public class Person {
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public Department Department { get; set; }
public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
public override bool Equals(object obj) {
if (obj is Person typedObj) {
return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
&& (this.Department == typedObj.Department);
}
return base.Equals(obj);
}
}
public enum Department { Motors, Electronics, Software }
}

Run Demo: List Box - Multiple Selection
Items Customization
The ItemTemplate property allows you to customize the appearance of ListBox items. Use the template’s context
parameter to access a data object and its fields (for instance, you can get the value of a data field).
The example below demonstrates how to display the ListBox’s items in a card-like view. Each item shows an employee’s first name, last name, photo, and phone number.
@inject NwindDataService NwindDataService
<DxListBox Data="@Data"
@bind-Value="@Value"
CssClass="cw-400 chi-220">
<ItemTemplate>
<div class="listbox-item-template">
<img src="@StaticAssetUtils.GetImagePath(GetImageFileName(context))" />
<div class="listbox-item-template-text">
<span>@context.FirstName @context.LastName</span>
<span class="listbox-item-template-text-phone">@context.HomePhone</span>
</div>
</div>
</ItemTemplate>
</DxListBox>
@code {
IEnumerable<Employee> Data { get; set; }
Employee Value { get; set; }
protected override async Task OnInitializedAsync() {
Data = await NwindDataService.GetEmployeesAsync();
Value = Data.FirstOrDefault();
}
string GetImageFileName(Employee employee) {
return $"employees/item-template{employee.EmployeeId}.jpg";
}
}
.listbox-item-template {
display: flex;
align-items: center;
}
.listbox-item-template > img {
border-radius: 50%;
width: 2rem;
height: 2rem;
}
img + .listbox-item-template-text {
margin-left: 1rem;
}
.listbox-item-template-text {
display: flex;
flex-flow: column;
}
.listbox-item-template-text-phone {
opacity: 0.65;
}

Run Demo: ListBox - ItemTemplate
Multiple Columns
The List Box can display data across multiple columns. To create columns, use DxListEditorColumn objects that include the following options for column customization:
- FieldName - Specifies the data source field that populates column items.
- Caption - Specifies the column header.
- Visible - Specifies the column visibility.
- VisibleIndex - Specifies the column display order.
- Width - Specifies the column width.
@using StaffData
<DxListBox Data="@Staff.DataSource"
@bind-Values="@Values"
style="height: 232px;">
<DxListEditorColumn FieldName="Id" Width="50px" />
<DxListEditorColumn FieldName="FirstName" Caption="Name"/>
<DxListEditorColumn FieldName="LastName" Caption="Surname"/>
</DxListBox>
@code {
IEnumerable<Person> Values { get; set; } = Staff.DataSource.Take(1);
}
namespace StaffData {
public static class Staff {
private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
var dataSource = new List<Person>() {
new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
return dataSource;
});
public static List<Person> DataSource { get { return dataSource.Value; } }
}
public class Person {
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public Department Department { get; set; }
public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
public override bool Equals(object obj) {
if (obj is Person typedObj) {
return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
&& (this.Department == typedObj.Department);
}
return base.Equals(obj);
}
}
public enum Department { Motors, Electronics, Software }
}

Run Demo: List Box – Multiple Columns
Set the ListRenderMode property to ListRenderMode.Virtual to enable virtual scrolling. In this mode, the List Box renders data on demand when a user scrolls list items.
@using StaffData
<DxListBox Data="@Staff.DataSource"
TData="Person"
TValue="Person"
ListRenderMode="ListRenderMode.Virtual">
</DxListBox>
namespace StaffData {
public static class Staff {
private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
var dataSource = new List<Person>() {
new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
return dataSource;
});
public static List<Person> DataSource { get { return dataSource.Value; } }
}
public class Person {
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public Department Department { get; set; }
public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
public override bool Equals(object obj) {
if (obj is Person typedObj) {
return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
&& (this.Department == typedObj.Department);
}
return base.Equals(obj);
}
}
public enum Department { Motors, Electronics, Software }
}
Run Demo: List Box - Virtual Scrolling
You can add a standalone List Box or the Form Layout component to the Blazor’s standard EditForm. This form validates user input based on data annotation attributes defined in a model and indicates errors.
<EditForm Model="@model" Context="EditFormContext">
<DataAnnotationsValidator />
<DxFormLayout >
<DxFormLayoutItem Caption="Values:" ColSpanMd="6" >
<DxListBox NullText="Select values ..."
ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto"
Data="@(new List<string>() { "Defense", "Exploration", "Diplomacy" })"
@bind-Values="@model.Values" />
</DxFormLayoutItem >
@*...*@
</DxFormLayout>
</EditForm>
@code {
private Model model=new Model();
}
public class Model
{
[Required(ErrorMessage = "Values should be selected.")]
public IEnumerable<string> Values { get; set; }
// ...
}
If you handle the ValueChanged
event and cannot use two-way binding, specify the ValueExpression or ValuesExpression property to identify the value passed to the event handler.
For more information, refer to the following help topic: Validate Input.
Run Demo: Form Validation
Read-Only State
<DxListBox>
supports a read-only state. Set the ReadOnly property to true
to activate this option.
@using StaffData
<DxListBox Data="@Staff.DataSource"
Values="@Values"
ReadOnly="true" />
@code {
IEnumerable<Person> Values => Staff.DataSource.Take(1);
}
namespace StaffData {
public static class Staff {
private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
var dataSource = new List<Person>() {
new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
return dataSource;
});
public static List<Person> DataSource { get { return dataSource.Value; } }
}
public class Person {
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public Department Department { get; set; }
public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
public override bool Equals(object obj) {
if (obj is Person typedObj) {
return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
&& (this.Department == typedObj.Department);
}
return base.Equals(obj);
}
}
public enum Department { Motors, Electronics, Software }
}
Run Demo: List Box - Read-Only and Disabled Modes
Troubleshooting
If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.
Inheritance
ObjectComponentBaseDevExpress.Blazor.Base.DxAsyncDisposableComponentDevExpress.Blazor.Base.DxDecoratedComponent
See Also