TagBox - Data Shaping

• Dec 03, 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

When a user enters text in the edit box, the TagBox searches for this text, filters items based on the search string, and highlights matches. Users can use special characters to create composite criteria. Refer to the following section for more information: Search Syntax.

You can use the following API members to configure search and filter capabilities:

• SearchMode — Specifies the search mode. You can set this property to Disabled to prevent users from text searching.
• SearchFilterCondition — Specifies the search and filter condition (Contains/Default, Equals, or StartsWith).
• SearchTextParseMode — Specifies how the component combines words in the search query. If the 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.
• SearchDelay - Specifies the delay between a user’s last input in the edit box and the initiation of the search.

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