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.

Remarks

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:

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 <DxListBox>…</DxListBox> markup to a .razor file.
3. Bind the component to data.
4. 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.

Razor

@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);
}

Person

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 }
}

Staff

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.

Razor

@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; }
}

StaffData

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.

Razor

@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";
    }
}

CSS

.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.

Razor

@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);
}

StaffData

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

Virtual Scrolling

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.

Razor

@using StaffData

<DxListBox Data="@Staff.DataSource"
           TData="Person"
           TValue="Person"
           ListRenderMode="ListRenderMode.Virtual">
</DxListBox>

StaffData

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

Input Validation

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.

Razor

<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();
}

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.

Razor

@using StaffData

<DxListBox Data="@Staff.DataSource"
           Values="@Values"
           ReadOnly="true" />

@code {
    IEnumerable<Person> Values => Staff.DataSource.Take(1);
}

StaffData

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.

Implements

IHandleEvent

IHandleAfterRender

IAsyncDisposable

IComponent

Inheritance

Object

ComponentBase

DevExpress.Blazor.Base.DxAsyncDisposableComponent

DevExpress.Blazor.Base.DxDecoratedComponent

DxComponentBase

DxDataEditor<TData>

DxListBox<TData, TValue>