blazor-405402-components-data-editors-listbox-templates.md
List Box templates are RenderFragment<TValue> type properties. These render fragments can contain both markup and other Razor components. A template’s Razor markup can access an implicit parameter named context. This parameter is derived from the TValue type and contains template-related members.
You can use the Context attribute to change the parameter name. This name change is essential when you nest components that contain RenderFragment<TValue> properties, otherwise, the following error can occur: The child content element ‘ChildContent’ of component ‘X’ uses the same parameter name (‘context’) ….
The ItemDisplayTemplate property allows you to customize the appearance of List Box items. The property accepts a ListBoxItemDisplayTemplateContext<TData> object as the context parameter. You can use the parameter’s members to get information about items:
The following code snippet displays List Box items as contact cards. Each item shows an employee’s first name, last name, photo, and phone number.
@inject NwindDataService NwindDataService
<DxListBox Data="@Data"
@bind-Value="@Value"
SizeMode="Params.SizeMode"
CssClass="cw-400 chi-220">
<ItemDisplayTemplate>
<div class="listbox-item-template">
<div class="listbox-item-template-text">
<span>@context.DataItem.FullName</span>
<span class="listbox-item-template-text-phone">@context.DataItem.HomePhone</span>
</div>
</div>
</ItemDisplayTemplate>
</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;
}
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
public partial class Employee {
public Employee() {
this.Orders = new List<Order>();
}
public int EmployeeId { get; set; }
public string LastName { get; set; }
public string FirstName { get; set; }
public string Title { get; set; }
public string TitleOfCourtesy { get; set; }
public Nullable BirthDate { get; set; }
public Nullable HireDate { get; set; }
public string Address { get; set; }
public string City { get; set; }
public string Region { get; set; }
public string PostalCode { get; set; }
public string Country { get; set; }
public string HomePhone { get; set; }
public string Extension { get; set; }
public byte[] Photo { get; set; }
public string Notes { get; set; }
public Nullable<int> ReportsTo { get; set; }
public string PhotoPath { get; set; }
public string GroupName { get; set; }
public virtual ICollection<Order> Orders { get; set; }
public string Text => $"{FirstName} {LastName} ({Title})";
public string FullName => $"{FirstName} {LastName}";
public string ImageFileName => $"employees/{EmployeeId}.jpg";
}
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using BlazorDemo.Data.Northwind;
using BlazorDemo.DataProviders;
namespace BlazorDemo.Services {
public partial class NwindDataService {
public Task<IEnumerable<Employee>> GetEmployeesAsync(CancellationToken ct = default) {
// Return your data here
}
}
}
public class Startup {
public void ConfigureServices(IServiceCollection services) {
// ...
services.AddScoped<NwindDataService>();
}
}
Run Demo: ListBox - Item Display Template
Use the following properties to customize cell appearance in a multi-column List Box.
| Property | Container | Scope |
|---|---|---|
| ColumnCellDisplayTemplate | DxListBox | All cells in a List Box |
| CellDisplayTemplate | DxListEditorColumn | Cells in the current column |
These properties can be combined within a single List Box. If both templates are defined, the column-specific CellDisplayTemplate takes precedence over the global ColumnCellDisplayTemplate for cells in that particular column. This functionality allows you to set a common template for all columns and then override it for individual columns that require different formatting.
The following code snippet customizes the appearance of different columns in a List Box control.
<DxListBox Data="Subscriptions.Plans"
@bind-Value="SelectedPlan">
<Columns>
<DxListEditorColumn FieldName="Name" Caption="Plan">
<CellDisplayTemplate>
<div class="text-left">
<b>@context.Value Subscription</b>
</div>
</CellDisplayTemplate>
</DxListEditorColumn>
<DxListEditorColumn FieldName="PriceMonth" Caption="Month" Width="70px" />
<DxListEditorColumn FieldName="PriceQuarter" Caption="Quarter" Width="70px" />
<DxListEditorColumn FieldName="PriceYear" Caption="Year" Width="70px" />
</Columns>
<ColumnCellDisplayTemplate>
<div class="text-right">
@($"{context.Value:C}")
</div>
</ColumnCellDisplayTemplate>
</DxListBox>
@code {
SubscriptionPlan SelectedPlan { get; set; }
}
public class SubscriptionPlan(
int id,
string name,
int priceMonth,
int priceQuarter,
int priceYear
)
{
public int Id { get; set; } = id;
public string Name { get; set; } = name;
public int PriceMonth { get; set; } = priceMonth;
public int PriceQuarter { get; set; } = priceQuarter;
public int PriceYear { get; set; } = priceYear;
}
public static class Subscriptions
{
public static List<SubscriptionPlan> Plans { get; } = [
new SubscriptionPlan(1, "Basic", 10, 25, 90),
new SubscriptionPlan(2, "Standard", 20, 50, 180),
new SubscriptionPlan(3, "Premium", 30, 75, 270),
new SubscriptionPlan(4, "Enterprise", 50, 125, 450)
];
}
.text-right {
text-align: right;
}
.text-left {
text-align: left;
}
Run Demo: List Box - Cell Display Template
The List Box displays an empty data area in the following cases:
Use the EmptyDataAreaTemplate to customize content displayed in the empty region. The template’s context parameter includes the IsDataLoading property that allows you to determine whether the List Box data is still loading data.
The following code snippet embeds the Wait Indicator component into the List Box.
@inject NwindDataService NwindDataService
<DxListBox TData="@WebApiLookup" TValue="string"
ListRenderMode="ListRenderMode.Virtual"
CssClass="cw-400 chi-220"
CustomData="@LoadCustomData"
@key="ComponentKey">
<EmptyDataAreaTemplate>
@if (context.IsDataLoading) {
<div class="empty-data-area-template">
<div class="d-flex flex-column">
<DxWaitIndicator Visible="true"
CssClass="m-auto"
AnimationType="WaitIndicatorAnimationType.Spin" />
<p class="dxbl-text d-block mt-1">Loading, please wait...</p>
</div>
</div>
}
</EmptyDataAreaTemplate>
</DxListBox>
@code {
[Inject] protected HttpClient Client { get; set; }
Guid ComponentKey { get; set; } = Guid.NewGuid();
async Task<LoadResult> LoadCustomData(DataSourceLoadOptionsBase options, CancellationToken cancellationToken) {
using var response = await Client.GetAsync(options.ConvertToGetRequestUri
("https://js.devexpress.com/Demos/NetCore/api/DataGridWebApi/CustomersLookup"), cancellationToken);
response.EnsureSuccessStatusCode();
if(options.RequireTotalCount)
await Task.Delay(3000, cancellationToken);
using var responseStream = await response.Content.ReadAsStreamAsync();
var result = await JsonSerializer.DeserializeAsync<LoadResult>(responseStream, cancellationToken: cancellationToken);
return result;
}
void ReloadListBox() {
ComponentKey = Guid.NewGuid();
}
public class WebApiLookup {
public string Text { get; set; }
public string Value { get; set; }
}
}
.empty-data-area-template {
display: flex;
justify-content: center;
align-items: center;
width: 100%;
height: 100%
}
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
public partial class Employee {
public Employee() {
this.Orders = new List<Order>();
}
public int EmployeeId { get; set; }
public string LastName { get; set; }
public string FirstName { get; set; }
public string Title { get; set; }
public string TitleOfCourtesy { get; set; }
public Nullable BirthDate { get; set; }
public Nullable HireDate { get; set; }
public string Address { get; set; }
public string City { get; set; }
public string Region { get; set; }
public string PostalCode { get; set; }
public string Country { get; set; }
public string HomePhone { get; set; }
public string Extension { get; set; }
public byte[] Photo { get; set; }
public string Notes { get; set; }
public Nullable<int> ReportsTo { get; set; }
public string PhotoPath { get; set; }
public string GroupName { get; set; }
public virtual ICollection<Order> Orders { get; set; }
public string Text => $"{FirstName} {LastName} ({Title})";
public string FullName => $"{FirstName} {LastName}";
public string ImageFileName => $"employees/{EmployeeId}.jpg";
}
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using BlazorDemo.Data.Northwind;
using BlazorDemo.DataProviders;
namespace BlazorDemo.Services {
public partial class NwindDataService {
public Task<IEnumerable<Employee>> GetEmployeesAsync(CancellationToken ct = default) {
// Return your data here
}
}
}
public class Startup {
public void ConfigureServices(IServiceCollection services) {
// ...
services.AddScoped<NwindDataService>();
}
}