TagBox - Data Shaping

• Jul 06, 2025
• 6 minutes to read

Group Data

The Blazor TagBox allows you to organize list items into groups. This enhance user experience by allowing users to locate required values faster. To group data, specify the GroupFieldName property. Values from the specified field appear within group headers.

Note the following specifics:

• The TagBox supports only one group level.
• Users cannot collapse groups.
• Group headers do not take part in search operations.
• Multi-column TagBox controls also support groups.
• You can use the GroupHeaderDisplayTemplate property to customize group headers.

The following code organizes data items into groups based on the Country data source field:

Razor

@inject NwindDataService NwindDataService

<DxTagBox Data="@Data"
          @bind-Values="@Values"
          TextFieldName="@nameof(Customer.ContactName)"
          GroupFieldName="@nameof(Customer.Country)"
          SearchMode="@ListSearchMode.AutoSearch"
          SearchFilterCondition="@ListSearchFilterCondition.Contains"
          InputId="tbGrouping">
</DxTagBox>

@code {
    IEnumerable<Customer> Data { get; set; }
    IEnumerable<Customer> Values { get; set; }
    protected override async Task OnInitializedAsync() {
        Data = await NwindDataService.GetCustomersAsync();
        Values = Data.Where(x => x.Country == "Argentina").Take(1);
    }
}

Customer.cs

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;

namespace BlazorDemo.Data.Northwind {
    public partial class Customer {
        public Customer() {
            Orders = new HashSet<Order>();
        }
        public string CustomerId { get; set; }
        public string CompanyName { get; set; }
        public string ContactName { get; set; }
        public string ContactTitle { 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 Phone { get; set; }
        public string Fax { get; set; }
        public virtual ICollection<Order> Orders { get; set; }
    }
}

NwindDataService.Customer.cs

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<Customer>> GetCustomersAsync(CancellationToken ct = default) {
            // Return your data here
        }
    }
}

Startup.cs

using BlazorDemo.Services;
using Microsoft.Extensions.DependencyInjection;

public class Startup {
    public void ConfigureServices(IServiceCollection services) {
        // ...
        services.AddScoped<NwindDataService>();
    }
}

Run Demo: TagBox – Group Data

Search and Filter Data

The DevExpress Blazor TagBox can search for text, and filter and highlight search results. Use the following API members to enable search and filter capabilities:

• SearchMode — Specifies whether the component can search for text that users type in the edit box. When the AutoSearch mode is active, the TagBox filters its items based on the search string and highlights string matches. The search operation includes all visible columns.

  Users can use special characters to create composite criteria. Refer to the following section for additional information: Search Syntax.

• SearchFilterCondition — Specifies the search and filter condition (Contains, Equals, or StartsWith).
• SearchTextParseMode — Specifies how the component combines words into the search query. If search text contains multiple words separated by spaces, words can be treated as single or individual conditions. The GroupWordsByAnd, GroupWordsByOr, and ExactMatch modes are available.
• SearchEnabled - Specifies whether the component can search text in cells of the current column.

Razor

<DxTagBox Data="Staff.DataSource" 
          @bind-Values="@Values"
          TextFieldName="@nameof(Person.FirstName)"
          ValueFieldName="@nameof(Person.Id)"
          SearchMode="ListSearchMode.AutoSearch"
          SearchFilterCondition="ListSearchFilterCondition.Contains">
    <Columns>
        <DxListEditorColumn FieldName="FirstName"></DxListEditorColumn>
        <DxListEditorColumn FieldName="LastName"></DxListEditorColumn>
        <DxListEditorColumn FieldName="Department" SearchEnabled="false"></DxListEditorColumn>
    </Columns>
</DxTagBox>

@code{
    IEnumerable<int> 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 }
}

When a user types text into the edit box, the TagBox filters and highlights search results.

Run Demo: TagBox - Search and Filter Data

Note

If you use the EditBoxDisplayTemplate property and need to enable filter mode, you should add a DxInputBox object to the template markup.

Disabled Items

You can disable individual items in the TagBox drop-down list. To do this, use the DisabledFieldName property. The property specifies a Boolean field that stores each item’s enabled or disabled state. Disabled items are grayed out and users cannot select them.

Note

Disabled items can improve component usability, but cannot replace adequate security measures. Users may still be able to select disabled items on the client side, so you should implement appropriate security checks in your code.

Razor

@inject NwindDataService NwindDataService

<DxListBox Data="@Products"
           @bind-Values="@SelectedProducts"
           TextFieldName="@nameof(Product.ProductName)"
           DisabledFieldName="@nameof(Product.Discontinued)"
           SelectionMode="ListBoxSelectionMode.Multiple"
           CssClass="cw-400 chi-220">
</DxListBox>

@code {
    IEnumerable<Product> Products { get; set; }
    IEnumerable<Product> SelectedProducts { get; set; }
    protected override async Task OnInitializedAsync() {
        Products = await NwindDataService.GetProductsAsync();
        SelectedProducts = Products.Take(1);
    }
}

Product.cs

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;

namespace BlazorDemo.Data.Northwind {
    public partial class Product {
        public Product() {
            OrderDetails = new HashSet<OrderDetail>();
        }
        public int ProductId { get; set; }
        public string ProductName { get; set; }
        public int? SupplierId { get; set; }
        public int? CategoryId { get; set; }
        public string QuantityPerUnit { get; set; }
        public decimal? UnitPrice { get; set; }
        public short? UnitsInStock { get; set; }
        public short? UnitsOnOrder { get; set; }
        public short? ReorderLevel { get; set; }
        public bool Discontinued { get; set; }
        public bool InStock => !Discontinued;
        public virtual Category Category { get; set; }
        public virtual Supplier Supplier { get; set; }
        public virtual ICollection<OrderDetail> OrderDetails { get; set; }
    }
}

NwindDataService.Product.cs

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<Product>> GetProductsAsync(CancellationToken ct = default) {
            // Return your data here
        }
    }
}

Startup.cs

using BlazorDemo.Services;
using Microsoft.Extensions.DependencyInjection;

public class Startup {
    public void ConfigureServices(IServiceCollection services) {
        // ...
        services.AddScoped<NwindDataService>();
    }
}

Run Demo: TagBox – Disabled Items