DxTagBox<TData, TValue> Class

An editor that allows users to select multiple items (tags) from the drop-down list.

Assembly: DevExpress.Blazor.v24.2.dll

Declaration

public class DxTagBox<TData, TValue> :
    DxDropDownListEditorBase<TData, TValue>,
    ITagBoxComponent<TData, TValue>,
    ITagBox<TData, TValue>,
    IDropDownListEditorBase<TData, TValue>,
    IListEditorBase<TData, TValue>,
    IEditorBase,
    IDropDownOwner,
    IFocusableEditor,
    ITagBoxAccessor<TData>,
    IDropDownListEditorAccessor<TData>,
    IListEditorAccessorBase<TData>,
    ITagBoxSelectionProviderOwner<TData, TValue>,
    IDropDownListEditorSelectionProviderOwner<TData, TValue>,
    IListEditorSelectionProviderOwner<TData, TValue>

Type Parameters

Name	Description
TData	The data item type.
TValue	The value type.

Remarks

The DevExpress TagBox for Blazor (<DxTagBox>) component displays a drop-down window with a list of strings. Users can select multiple items from a list and type text in the editor to filter list items that contain the search string. Users can also use keyboard to navigate to the editor’s items and select them.

TagBox Overview

Run Demo: TagBox - Overview

Add a TagBox to a Project

Follow the steps below to add the TagBox 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 <DxTagBox>…</DxTagBox> markup to a .razor file.
Bind the component to data.
Configure the component: customize the layout and appearance of items and tags, add a clear button and placeholder, and so on (see the sections below).

.NET 8 and .NET 9 Specifics

Blazor TagBox does not support static render mode. Enable interactivity to use the component in your application. Refer to the following topic for more details: Enable Interactive Render Mode.

Bind to Data

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).

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

TagBox Bind To Data

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
Data Source

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

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

TagBox Overview

If the TextFieldName property is not specified, the TagBox’s 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.

Tags, Custom Tags, and List Items

The TagBox’s drop-down window displays a list of 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 the selected items in the list, set the HideSelectedItems property to false.

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

TagBox Overview

<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 the tag collection’s changes.

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

Multiple Columns

The TagBox control can display data across multiple columns. Follow the steps below to create columns:

Add a <Columns> tag to the component’s markup to declare the column collection.
Populate the Columns collection with DxListEditorColumn objects. These objects include the following properties:
- Caption - Specifies the column’s caption text.
- FieldName - Specifies the data source field that populates column items in multi-column editors.
- SearchEnabled - Specifies whether the component can search text in cells of the current column.
- Visible - Specifies whether the column is visible.
- VisibleChanged - Fires when the column visibility changes.
- VisibleIndex - Specifies a column’s position among other columns.
- VisibleIndexChanged - Fires when the column’s visible index changes.
- Width - Specifies the column’s width.

To format tag values, use the EditFormat property.

Razor
StaffData

@using StaffData

<DxTagBox Data="@Staff.DataSource"
          @bind-Values="@SelectedStaff"
          EditFormat="{1} {2}">
    <Columns>
        <DxListEditorColumn FieldName="Id" Width="50px" />
        <DxListEditorColumn FieldName="FirstName" Caption="Name"/>
        <DxListEditorColumn FieldName="LastName" Caption="Surname"/>
    </Columns>
</DxTagBox>

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

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

TagBox - Multiple Columns

Run Demo: TagBox – Multiple Columns

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:

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

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

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

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

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

TagBox - Group Data

Run Demo: TagBox – Group Data

Clear Button and Placeholder

Set the ClearButtonDisplayMode property to Auto to show the Clear button when the TagBox has tags. Users can click this button to clear all the displayed tags (set the Tags property to null).

Use the NullText property to display the prompt text (placeholder) in TagBox when its Tags property is set to null.

Razor
Country

<DxTagBox NullText="Select countries..."
          Data="@CountryData.Countries"
          @bind-Values="@SelectedCountries"
          TextFieldName="@nameof(Country.CountryName)"
          ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto">
</DxTagBox>

@code {
    IEnumerable<Country> SelectedCountries { get; set; }
}

public class Country {
    public int Id { get; set; }
    public string CountryName { get; set; }
}

public static class CountryData {
    private static readonly Lazy<List<Country>> countries = new Lazy<List<Country>>(() => {
        return new List<Country>()
        {
            new Country() { Id = 0, CountryName = "USA" },
            new Country() { Id = 1, CountryName = "Germany" },
            new Country() { Id = 2, CountryName = "Japan" }
        };
    });
    public static List<Country> Countries { get { return countries.Value; } }
}

TagBox Clear Button

Run Demo: TagBox - Clear Button and Placeholder

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
StaffData

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

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.

TagBox - Filter Data

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’s 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 can not 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.

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

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

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

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

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

TagBox - Disabled Items

Run Demo: TagBox – Disabled Items

Customization

The TagBox component allows you to customize its appearance: the size, the appearance of the edit box, items, tags, and column cells.

Size Modes

Use the SizeMode property to specify a TagBox size. The following code snippet applies different size modes to TagBox components.

Razor
StaffData

@using StaffData

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

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

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

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

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

TagBox - Size modes

For more information, refer to the following topic: Size Modes.

Item Display Template

Use the ItemDisplayTemplate property to customize the appearance of TagBox items. The property accepts a TagBoxItemDisplayTemplateContext<TData> object as the context parameter. You can use the parameter’s members to obtain item information:

The following code snippet uses the ItemDisplayTemplate property to display TagBox items in a card-like view. Each item shows an employee’s first name, last name, photo, and phone number.

@inject NwindDataService NwindDataService

<DxTagBox Data="@Data"
          @bind-Values="@Values">
    <TagDisplayTemplate Context="tagContext">
        <div class="tagbox-tag-template">
            <img class="tagbox-tag-template-employee-photo" src="@StaticAssetUtils.GetImagePath(GetImageFileName(tagContext.DataItem))" alt="@tagContext.DataItem.FullName" />
            <div>@tagContext.DataItem.FullName</div>
            <DxButton Click="@tagContext.RemoveTagAction"
                        @onclick:stopPropagation
                        aria-label="Remove Tag"
                        CssClass="tagbox-tag-template-close-btn"
                        IconCssClass="tagbox-tag-template-close-btn-icon"
                RenderStyle="ButtonRenderStyle.None" RenderStyleMode="ButtonRenderStyleMode.Text">
            </DxButton>
        </div>
    </TagDisplayTemplate>
    <ItemDisplayTemplate>
        <div class="tagbox-item-template">
            <img class="tagbox-item-template-employee-photo" src="@StaticAssetUtils.GetImagePath(GetImageFileName(context.DataItem))" alt="@context.DataItem.FullName" />
            <div>
                <span class="tagbox-item-template-employee-first-name">@context.DataItem.FullName</span>
                <span class="tagbox-item-template-employee-home-phone">@context.DataItem.HomePhone</span>
            </div>
        </div>
    </ItemDisplayTemplate>
</DxTagBox>

@code {
    IEnumerable<Employee> Data { get; set; }
    IEnumerable<Employee> Values { get; set; }
    protected override async Task OnInitializedAsync() {
        Data = await NwindDataService.GetEmployeesAsync();
        Values = Data.Take(1);
    }
    string GetImageFileName(Employee employee) {
        return $"employees/item-template{employee.EmployeeId}.jpg";
    }
}

.tagbox-item-template {
    display: flex;
    align-items: center;
}
.tagbox-tag-template {
    display: flex;
    align-items: center;
    padding: 0.125em 0.5em 0.125em 0;
    position: relative;
}
.tagbox-tag-template:before {
    content: " ";
    position: absolute;
    background-color: currentColor;
    opacity: 0.15;
    border-radius: 16px;
    left: 0;
    top: 0;
    right: 0;
    bottom: 0;
    pointer-events: none;
}
.tagbox-item-template-employee-photo,
.tagbox-tag-template-employee-photo {
    margin-right: 0.5em;
    border-radius: 16px;
    border: 0 solid #000;
}
.tagbox-item-template-employee-photo {
    border-radius: 50%;
    width: 2rem;
    height: 2rem;
}
.tagbox-tag-template-employee-photo {
    width: 24px;
    height: 24px;
}
.tagbox-item-template-employee-home-phone {
    opacity: 0.65;
    display: block;
}
.tagbox-tag-template-close-btn {
    border: 0;
    border-radius: 3rem;
    box-shadow: none;
    font-weight: 600;
    padding: 0;
    width: 16px;
    height: 16px;
    margin: 0 0 0 0.5em;
    opacity: 0.5;
}
.tagbox-tag-template-close-btn:hover {
    opacity: 0.75;
}
.tagbox-tag-template-close-btn-icon {
    height: 16px;
    width: 16px;
    mask-image: url("images/icons/clear.svg");
    -webkit-mask-image: url("images/icons/clear.svg");
    background-size: contain;
    mask-repeat: no-repeat;
    -webkit-mask-repeat: no-repeat;
    background-position: center center;
    background-color: currentColor;
}

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<System.DateTime> BirthDate { get; set; }
    public Nullable<System.DateTime> 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>();
    }
}

TagBox - ItemTemplate

Run Demo: TagBox - ItemTemplate

Tag Display Template

Use the TagDisplayTemplate property to customize tag appearance. The property accepts a TagBoxTagDisplayTemplateContext<TData> object as the context parameter. You can use the parameter’s members to obtain tag information:

The following code snippet customizes a tag appearance according to its type and text.

@inject WorldcitiesDataService WorldcitiesDataService
<DxTagBox Data="@Data"
          TextFieldName="@nameof(City.CityName)"
          TData="City"
          TValue="City"
          AllowCustomTags="true"
          @bind-Tags="@Tags"
          ListRenderMode="ListRenderMode.Virtual">
    <TagDisplayTemplate Context="tagContext">
        @{
            var buttonStyleMode = tagContext.IsCustom ? ButtonRenderStyleMode.Contained : GetModeByID(tagContext.DataItem.CityName);
            var buttonStyle = tagContext.IsCustom ? ButtonRenderStyle.Dark : ButtonRenderStyle.Primary;
            <DxButton RenderStyle="@buttonStyle"
                      RenderStyleMode="@buttonStyleMode"
                      Text="@tagContext.DisplayText"
                      CssStyle="display:inline-block; padding-right: 0">
                @context
                <span @onclick="@tagContext.RemoveTagAction" style="display:inline-block; width: 1em; margin-left: 0.5em">
                    &times;
                </span>
            </DxButton>
        }
    </TagDisplayTemplate>
</DxTagBox>

@code {
    IEnumerable<City> Data { get; set; }
    IEnumerable<string> Tags { get; set; }
    protected override async Task OnInitializedAsync() {
        Data = await WorldcitiesDataService.GetCitiesAsync();
        Tags = new List<string>() { "New York", "Los Angeles", "Tokyo" };
    }
    ButtonRenderStyleMode GetModeByID(string cityName) {
        switch(cityName) {
            case "New York":
                return ButtonRenderStyleMode.Contained;
            case "Los Angeles":
                return ButtonRenderStyleMode.Outline;
            default:
                return ButtonRenderStyleMode.Text;
        }
    }
}

public class City {
    public int Id { get; set; }
    public int CountryId { get; set; }
    public string CityName { get; set; }
}

public static class CityData {
    private static readonly Lazy<List<City>> cities = new Lazy<List<City>>(() => {
        return new List<City>() {
            new City() { Id = 0, CountryId = 0, CityName = "Washington" },
            new City() { Id = 1, CountryId = 0, CityName = "New York" },
            new City() { Id = 2, CountryId = 0, CityName = "Los Angeles" },
            new City() { Id = 3, CountryId = 1, CityName = "Berlin" },
            new City() { Id = 4, CountryId = 1, CityName = "Munich" },
            new City() { Id = 5, CountryId = 1, CityName = "Hamburg" },
            new City() { Id = 6, CountryId = 2, CityName = "Tokyo" },
            new City() { Id = 7, CountryId = 2, CityName = "Osaka" },
            new City() { Id = 8, CountryId = 2, CityName = "Yokohama" }
        };
    });
    public static List<City> Cities { get { return cities.Value; } }
}

using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using BlazorDemo.Data.Worldcities;
using BlazorDemo.DataProviders;

namespace BlazorDemo.Services {
    public partial class WorldcitiesDataService {
        public Task<IEnumerable<City>> GetCitiesAsync(CancellationToken ct = default) {
            // Return your data here
        }
    }
}

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

TagBox Template

Run Demo: TagBox - Tag Display Template

Column Cell Display Template

The ColumnCellDisplayTemplate allows you to specify custom content and change cell appearance in TagBox columns. The template accepts a TagBoxColumnCellDisplayTemplateContext<TData> object as the context parameter. You can use the parameter’s members to obtain column information.

The following code customizes the appearance of different columns.

@inject NwindDataService NwindDataService

<DxTagBox TData="Product" TValue="Product" Data="@Products"
            @bind-Values="@SelectedProducts"
            TextFieldName="@nameof(Product.ProductName)"
            ListRenderMode="ListRenderMode.Virtual">
    <Columns>
        <DxListEditorColumn FieldName="@nameof(Product.ProductName)" Caption="Product" Width="30%" />
        <DxListEditorColumn FieldName="@nameof(Product.UnitPrice)" Caption="Unit Price" />
        <DxListEditorColumn FieldName="@nameof(Product.Quantity)" />
        <DxListEditorColumn FieldName="@nameof(Product.Discount)" />
        <DxListEditorColumn FieldName="@nameof(Product.Total)" />
    </Columns>
    <ColumnCellDisplayTemplate>
        @GetColumnCellTemplateRenderFragment(context)
    </ColumnCellDisplayTemplate>
</DxTagBox>


@code {
    const int SelectedProductsCount = 3;
    const int TotalPriceCeiling = 100;
    IEnumerable<Product> Products { get; set; }
    IEnumerable<Product> SelectedProducts { get; set; }
    const string AlignRightCssClass = "align-right";
    const string TextGreenCssClass = "text-green";
    const string TextRedCssClass = "text-red";

    protected override async Task OnInitializedAsync() {
        var invoices = await NwindDataService.GetInvoicesAsync();
        var products = await NwindDataService.GetProductsAsync();
        Products = invoices.Join(products, i => i.ProductId, p => p.ProductId, (i, p) =>
            new Product {
                ProductName = i.ProductName,
                UnitPrice = i.UnitPrice,
                Quantity = i.Quantity,
                Discount = i.Discount
            }
        );
        SelectedProducts = Products.Skip(1).Take(SelectedProductsCount);
    }
    RenderFragment GetColumnCellTemplateRenderFragment(TagBoxColumnCellDisplayTemplateContext<Product> context) {
        object displayValue;
        string cssClass = string.Empty;
        switch(context.Column.FieldName) {
            case nameof(Product.UnitPrice):
                cssClass = AlignRightCssClass;
                displayValue = $"{context.Value:c}";
                break;
            case nameof(Product.Quantity):
                cssClass = AlignRightCssClass;
                displayValue = context.DisplayText;
                break;
            case nameof(Product.Discount):
                displayValue = $"{context.Value:p}";
                break;
            case nameof(Product.Total):
                var value = context.DataItem.UnitPrice * context.DataItem.Quantity;
                var valueCssClass = value >= TotalPriceCeiling ? TextGreenCssClass : TextRedCssClass;
                cssClass = $"{AlignRightCssClass} {valueCssClass}";
                displayValue = $"{value:c}";
                break;
            default:
                displayValue = context.DisplayText;
                break;
        }
        return @<text><div class="@cssClass">@displayValue</div></text>;
    }

    public class Product {
        public string ProductName { get; set; }
        public decimal UnitPrice { get; set; }
        public int Quantity { get; set; }
        public float Discount { get; set; }
        public int Total { get; set; }
        public override bool Equals(object obj) {
            return obj is Product product && string.Equals(product.ProductName, ProductName) && product.Quantity == Quantity;
        }
        public override int GetHashCode() {
            return HashCode.Combine(ProductName, Quantity);
        }
    }
}

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<System.DateTime> BirthDate { get; set; }
    public Nullable<System.DateTime> 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
        }
    }
}

.empty-data-area-template {
    display: flex;
    justify-content: center;
    align-items: center;
    width: 100%;
    height: 100%;
    padding: 2rem 0;
}

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

TagBox - Column Cell Display Template

Run Demo: TagBox - Column Cell Display Template

Empty Data Area Template

The TagBox displays an empty data area in the following cases:

The Data property is unset.
The specified data source is empty.
None of the TagBox items matches the current search and filter condition.
You use the DataAsync property or the CustomData property to bind the TagBox to a data source. The component sends the first request to a remote data source and waits for a response.

Use the EmptyDataAreaTemplate to customize content displayed in this empty region. The template’s context parameter includes the IsDataLoading property that allows you to determine whether the TagBox is still loading data.

@inject NwindDataService NwindDataService

<DxTagBox Data="@DataItems"
          @bind-Values="@Items"
          CssClass="cw-480"
          NullText="Select an order..."
         >
    <EmptyDataAreaTemplate>
        @if (!context.IsDataLoading) {
            <div class="empty-data-area-template">
                <div class="d-flex flex-column">
                    No orders found
                </div>
            </div>
        }
    </EmptyDataAreaTemplate>
</DxTagBox>

@code {
    IEnumerable<string> DataItems { get; set; }
    IEnumerable<string> Items { get; set; }
}

.empty-data-area-template {
    display: flex;
    justify-content: center;
    align-items: center;
    width: 100%;
    height: 150px;
    padding: 2rem 0;
}

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<System.DateTime> BirthDate { get; set; }
    public Nullable<System.DateTime> 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>();
    }
}

TagBox - Empty Data Area Template

Run Demo: TagBox - Empty Data Area Template

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

Input Validation

When you add the TagBox to the Blazor’s standard EditForm, you can use the ValidateBy property to validate component tags and values.

The following code snippet uses the ValidateBy property to validate email addresses (custom tags) specified in the TagBox. In this example the following validation settings are specified:

the ValidateBy property is set to TagBoxValidateBy.Tags;
the Tags property’s bound field is marked with the Required and custom data annotation attributes that validate email formats.

After a user types an email address, the edit box is underlined in red or green: red indicates the editor contains an invalid tag(s) or is empty; green indicates the tags are valid.

Markup
EmailAddressesAttribute

<EditForm Model="@recipients" OnValidSubmit="@HandleValidSubmit" OnInvalidSubmit="@HandleInvalidSubmit">
    <DataAnnotationsValidator />
    <p>
        <label for="emails">Recipients:</label>
        <DxTagBox Id="emails"
                  NullText="Select email recipients"
                  Data="@Emails.DataSource"
                  TData="string"
                  TValue="string"
                  AllowCustomTags="true"
                  ValidateBy="TagBoxValidateBy.Tags"
                  ShowValidationIcon="true"
                  @bind-Tags="@recipients.Data">
        </DxTagBox>
        <ValidationMessage For="@(() => recipients.Data)" />
    </p>
    <button type="submit">Submit</button>
</EditForm>

@code {
    EmailRecipients recipients = new EmailRecipients();

    private void HandleValidSubmit() {
        Console.WriteLine("OnValidSubmit");
    }
    private void HandleInvalidSubmit() {
        Console.WriteLine("OnInvalidSubmit");
    }
}

using System.ComponentModel.DataAnnotations;

public class EmailRecipients {
    [Required]
    [EmailAdresses(ErrorMessage = "Invalid email")]
    public IEnumerable<string> Data { get; set;}
} 

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Parameter, AllowMultiple = false)]
public class EmailAdressesAttribute: ValidationAttribute {
    public override bool IsValid(object value) {
        IEnumerable<string> data = value as IEnumerable<string>;
        if (data != null) {
            foreach (var item in data)
                if (!item.Contains("@") || !item.Substring(item.IndexOf('@')).Contains("."))
                    return false;
            return true;
        } else
            return false;
    }
}

TagBox Validation

For more information, refer to the following help topic: Validate Input.

The DevExpress Blazor TagBox supports keyboard navigation. Users can focus the editor’s input element, navigate within the drop-down item list, and select tags. While DOM focus refers to the input element as the active element for keyboard interaction, visual focus can move to items in the drop-down list. Keyboard navigation is also supported in virtual scroll mode.

Run Demo: TagBox

Shortcut Keys for Input Element

The following shortcut keys are available when the editor’s input element is focused:

Shortcut Keys	Description
`Tab`	Moves focus to the next focusable element on a page. Note that tags in the input and the Clear button are excluded from the page tab sequence. If AllowCustomTags is set to `true`, the entered characters are applied as a custom tag.
`Shift` + `Tab`	Moves focus to the previous focusable element on a page.
Characters	If AllowCustomTags is set to `true`, adds characters to the input.
`Backspace`, `Delete`	If AllowCustomTags is set to `true`, removes characters in the input element. If there are no characters in the input, Backspace removes the last existing tag.
`Home`	If AllowCustomTags is set to `true`, moves the cursor to the start of the text input.
`End`	If AllowCustomTags is set to `true`, moves focus to the end of the text input.
`Right Arrow`	If AllowCustomTags is set to `true`, moves the cursor one character to the right in the input element. When the cursor reaches a right edge, nothing happens.
`Left Arrow`	If AllowCustomTags is set to `true`, moves the cursor one character to the left in the input element. When the cursor reaches a left edge, nothing happens.
`Alt` + `Down Arrow`	Opens the drop-down list, but keeps focus in the input element.

Shortcut Keys for Drop-Down Item List

The following shortcut keys are available when the drop-down list is opened:

Shortcut Keys	Description
`Up Arrow`	Moves focus one item up.
`Down Arrow`	Moves focus one item down.
`Ctrl` + `Shift` + `Home`	Moves focus to the first item in the list.
`Ctrl` + `Shift` + `End`	Moves focus to the last item in the list.
`Page Up`	Moves focus to the previous item page.
`Page Down`	Moves focus to the next item page.
`Tab`	Selects the focused item, updates the Tags parameter value, closes the drop-down list, moves focus to the input element.
`Enter`	Selects the focused item, updates the Tags parameter value, and closes the drop-down list.
`Escape`, `Alt` + `Up Arrow`	Closes the drop-down list.

The Tag Box does not currently allow you to navigate through elements in templated items.

Read-Only State

The TagBox supports a read-only state. Set the ReadOnly property to true to activate this mode.

<DxTagBox Data="@Fruits"
          @bind-Values="@SelectedFruits"
          ReadOnly="true"> 
</DxTagBox>

Run Demo: TagBox - Read-Only and Disabled Modes

Drop-Down List Width

Use the DropDownWidthMode property to specify the width of the drop-down list. The following values are available:

ContentOrEditorWidth (Default) - The list displays item text completely. The minimum list width matches the editor.
ContentWidth - The list width is equal to the width of the longest list item.
EditorWidth - The list width matches the editor. If item text does not fit the editor width, item text is displayed across multiple lines.

Run Demo: ComboBox – Drop-Down List Width

Run Demo: TagBox – Drop-Down List Width

Drop-Down Window Direction

Use the DropDownDirection property to specify the direction in which the TagBox’s drop-down window is displayed relative to the input element. The default value is Down. The following code changes the direction to Up:

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

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

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

TagBox

Note

If the editor is close to a browser window’s edge and there is not enough space to display the drop-down window in the specified direction, the drop-down window is displayed in the opposite direction.

HTML Attributes and Events

You can use HTML attributes and events to configure the TagBox.

<DxTagBox Data="@Strings" 
          @bind-Values="@Values" 
          maxlength="10" 
          @onclick="MyFunction">
</DxTagBox>

@code {
    void MyFunction(){
        //...
    }
}

Note that the TagBox’s CssClass property has priority over unmatched attributes (the Attributes property). For example, if you specify the class html attribute and the CssClass property, the last one has priority.

<DxTagBox Data="_data"
            @bind-Values="_values"
            class="myClass"
            CssClass="myCssClass" />

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Implements

ITagBox<TData, TValue>

IDropDownListEditorBase<TData, TValue>

IListEditorBase<TData, TValue>

IEditorBase

Inheritance

Object

ComponentBase

DxComponentBase

DevExpress.Blazor.Internal.ParameterTrackerComponent

DxEditorBase

DxListEditorBase<TData, TValue>

DxDropDownListEditorBase<TData, TValue>

DxTagBox<TData, TValue>

DxTagBox<TData, TValue> Class

Declaration

Type Parameters

Remarks

Add a TagBox to a Project

.NET 8 and .NET 9 Specifics

Bind to Data

Strongly Typed Collection

Custom Object Collection

Load Custom Data

Tags, Custom Tags, and List Items

Multiple Columns

Group Data

Clear Button and Placeholder

Search and Filter Data

Disabled Items

Customization

Size Modes

Item Display Template

Tag Display Template

Column Cell Display Template

Empty Data Area Template

Virtual Scrolling

Input Validation

Keyboard Navigation

Shortcut Keys for Input Element

Shortcut Keys for Drop-Down Item List

Read-Only State

Drop-Down List Width

Drop-Down Window Direction

HTML Attributes and Events

Troubleshooting

Implements

Inheritance