TagBox - Bind to Data

• Jul 06, 2025
• 5 minutes to read

This topic describes how to bind the Blazor TagBox to data in different scenarios.

Strongly Typed Collection

Use the Data property to bind the TagBox 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).

The TagBox’s drop-down window lists items from a bound data source. Once a user selects an item, its text is displayed as a new tag and the item is hidden from the list. To display selected items in the list, set the HideSelectedItems property to false.

Use the Values property to specify the component’s selected value/item collection. You can use the @bind attribute to bind the Values property to a data field. Refer to the following topic for details: Two-Way Data Binding.

<DxTagBox Data="@Cities" @bind-Values="@Values"></DxTagBox>

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

    IEnumerable<string> Values { get; set; }
}

The TagBox can detect IQueryable collections and use benefits of the corresponding LINQ query providers (such as Entity Framework).

Custom Object Collection

You can bind the TagBox to a data collection (Data) that stores custom objects (IEnumerable<CustomType>). The Values collection can also contain custom objects. In this case, you need to override the following methods for your custom object:

• GetHashCode(). The TagBox uses hash codes to compare items. Override this method to make sure that compared objects have the same hash code.

• Equals. The default Equals method determines whether two object instances are equal. The compared items will not be equal if they are different instances (even if they have exactly the same properties). As a result, the component will not display the selected items.

You also need to set the TextFieldName property. It specifies the custom object’s field name that returns strings to be shown in the TagBox. If the TextFieldName property is not specified, the TagBox component searches for a Text field in the data source and uses this field as a text field. Otherwise, the TagBox is populated with CustomType.ToString() values.

As an alternative, you can use KeyFieldName and KeyFieldNames properties to specify which field the TagBox should use as an identifier to compare items.

Razor

@using BlazorApp.Data

<DxTagBox Data="@Staff.DataSource"
          @bind-Values="@SelectedStaff"
          TextFieldName="@nameof(Person.Text)">
</DxTagBox>

@code {
    IEnumerable<Person> SelectedStaff { get; set; } = new List<Person>() { Staff.DataSource[0] };
}

Data Source

using System;
using System.Collections.Generic;

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 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 override int GetHashCode() {
            return HashCode.Combine(Id, FirstName, LastName);
        }

    public enum Department { Motors, Electronics, Software }

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

If the TextFieldName property is not specified, the TagBox items are populated with CustomType.ToString() values.

Load Custom Data

When you bind an editor to data from a Web API service, assign the data type to the component’s T parameter and use the CustomData property to implement custom data load logic.

View Example: Data Editors for Blazor - Custom data binding

You can also enable Virtual Scrolling to improve client-side performance.

Virtual Scrolling

When virtual scrolling is activated (ListRenderMode is set to Virtual), the TagBox renders data on demand when a user scrolls its items.

<DxTagBox Data="@Strings"
          @bind-Values="@Values"
          ListRenderMode="ListRenderMode.Virtual">
</DxTagBox>

Run Demo: TagBox - Virtual Scrolling

Allow Custom Tags

Set the AllowCustomTags property to true to allow users to type tags that are not in the bound list.

<DxTagBox Data="@Cities"
          AllowCustomTags="true"
          @bind-Tags="@Tags"
          @bind-Values="@Values"
          HideSelectedItems="false">
</DxTagBox>

@code {
    IEnumerable<string> Tags = new List<string>() {
        "London",
        "New York"
    };

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

    IEnumerable<string> Values;
}

Use the Tags property to specify tags in code. You can use the @bind attribute to bind the Tags property to a data field. Refer to the following topic for details: Two-Way Data Binding. If you do not use two-way binding, handle the TagsChanged event to respond to tag collection changes.

View Example: Use the DxTagBox control as a filter for a Grid column