DxListBox<TData, TValue> Class

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.dll

Declaration

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

Type Parameters

Remarks

DevExpress List Box for Blazor (<DxListBox>) allows you to display a list of selectable items from a data source.

Add List Box to a Project

To add the <DxListBox> component to an application, follow the steps below:

1. Create an application. If you use Microsoft project templates, configure the application as described in this topic: Use Microsoft Templates.
2. Add the <DxListBox>...</DxListBox> markup to your application.
3. Bind the component to data (see details below).
4. Configure the component (see the sections below).

Bind to Data

Use the Data property to bind the List Box to an IEnumerable<T> data source synchronously. If the data source is large or requires access to a remote web service over slow networks, use the DataAsync property instead. It allows you to load data asynchronously and await completion without blocking application code execution.

<DxListBox Data="@Cities"></DxListBox>

@code {
  IEnumerable<string> Cities = new List<string>() {
    "London",
    "Berlin",
    "Paris",
  };
}

If a data source stores custom objects (IEnumerable<CustomType>), use 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="@Persons.DataSource"
           TextFieldName="Text">
</DxListBox>

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

using System;
using System.Collections.Generic;

namespace BlazorApp.Data {
    public static class Persons {
        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; } }
    }
}

To bind the List Box to a data source that is not of the IEnumerable<T> type, assign the data source type to the component's T parameter and use the CustomData property to implement the data load logic.

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.

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

<DxListBox Data="@Persons.DataSource"
           TextFieldName="Text"
           SelectionMode="ListBoxSelectionMode.Multiple"
           ShowCheckboxes="true"
           @bind-Values="@Values">
</DxListBox>

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

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.
• Visible - Specifies the column visibility.
• VisibleIndex - Specifies the column display order.
• Width - Specifies the column width.

<DxListBox Data="@Persons.DataSource"
           @bind-Values="@Values"
           style="height: 232px;">
    <DxListEditorColumn FieldName="Id" Width="50px" />
    <DxListEditorColumn FieldName="FirstName" />
    <DxListEditorColumn FieldName="LastName" />
</DxListBox>

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

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="@Persons.DataSource"
           ListRenderMode="ListRenderMode.Virtual">
</DxListBox>

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.

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

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.

Read-Only State

<DxListBox> supports a read-only state. Set the ReadOnly property to true to activate this option.

<DxListBox ReadOnly="true"> </DxListBox>