DxListBox<TData, TValue> Class
A List Box component.
Namespace: DevExpress.Blazor
Assembly: DevExpress.Blazor.v21.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.
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 page. - 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);
}
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.
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.
<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); }
}
}
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";
}
}
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);
}
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.
<DxListBox Data="@Staff.DataSource"
TData="Country"
TValue="Country"
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" >
<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();
}
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.
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);
}
Troubleshooting
If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.