DxListBox<TData, TValue> Class

A List Box component.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v20.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxListBox<TData, TValue> :
    DxResizableEditorBase<TData, ListBoxJSInteropProxy>,
    IDataSourceSettings<TData>,
    IHandleDataLayoutChanged,
    IServiceProviderAccessor,
    IRequireSelfCascading,
    IListBoxJSInteropProxyServer,
    IJSCallback

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 page.
3. Bind the component to data.
4. Configure the component (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 Values property to specify to the component’s selected value/item collection. You can use the @bind attribute to bind the Values property to a data field. Refer to 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 enum Department { Motors, Electronics, Software }

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

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

If your data is stored on a remote service and is loaded through a Web API, assign the data type to the component’s T parameter and use the CustomData property to implement data load logic.

Run Demo: List Box - Overview

Item Selection

A user should click a List Box item to select it. To access the selected item in code, use the Values collection. To handle selection changes, use the ValuesChanged event.

To enable multi selection in List Box, set the SelectionMode property to ListBoxSelectionMode.Multiple. In this mode, 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.

To disable selection in List Box, set the SelectionMode property to ListBoxSelectionMode.None.

Note

You can also enable the ShowCheckboxes property to allow users to select items via checkboxes.

The code below demonstrates how to enable multiple selection via checkboxes in List Box.

<DxListBox Data="@Staff.DataSource"
           TextFieldName="@nameof(Person.Text)"
           SelectionMode="ListBoxSelectionMode.Multiple"
           ShowCheckboxes="true"
           @bind-Values="@Values">
</DxListBox>

@code {
    IEnumerable<Person> Values {
        get => Values;
        set { Values = value; InvokeAsync(StateHasChanged); }
    }
}

Run Demo: List Box - Multiple Selection

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.

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

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 loads data on demand when a user scrolls list items.

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

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" >
            <Template>
                <DxListBox NullText="Select values ..."
                           ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto"
                           Data="@(new List<string>() { "Defense", "Exploration", "Diplomacy" })"
                           @bind-Values="@model.Values" />
            </Template>
        </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; }
    // ...
}

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.

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

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

Run Demo: List Box - Read-Only and Disabled Modes

Implements

IHandleEvent

IHandleAfterRender

IAsyncDisposable

IDisposable

IComponent

Inheritance

Object

ComponentBase

DevExpress.Blazor.Base.DxAsyncDisposableComponent

DevExpress.Blazor.Base.DxDecoratedComponent

DxComponentBase

DxComponentBase<DevExpress.Blazor.Internal.JSInterop.ListBoxJSInteropProxy>

DevExpress.Blazor.Internal.DxEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.ListBoxJSInteropProxy>

DxDataEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.ListBoxJSInteropProxy>

DxResizableEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.ListBoxJSInteropProxy>

DxListBox<TData, TValue>