DxTagBox<TData, TValue> Class

A TagBox component.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v20.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxTagBox<TData, TValue> :
    DxDropDownBase<TData, TagBoxJSInteropProxy>,
    IDataSourceSettings<TData>,
    IInputBase,
    IServiceProviderAccessor,
    IRequireSelfCascading,
    IDropDownWidthModeAccessor,
    ITagBoxJSInteropProxyServer,
    IJSCallback,
    IDisposable

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 the Up arrow, Down arrow, and Enter keys to navigate to the editor’s items and select them. When a user presses and holds an arrow key, the editor’s window continuously navigates between items.

Run Demo: TagBox - Overview

Add a TagBox to a Project

Follow the steps below to add the TagBox component to an application:

1. 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.
2. Add the <DxTagBox>…</DxTagBox> markup to a Razor page.
3. Bind the component to data.
4. Configure the component (see the sections below).

Bind to Data

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

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

If you bind the TagBox to a data collection that stores custom objects (IEnumerable<CustomType>), override the object’s Equals method and set the TextFieldName property. This property specifies the custom object’s field name that returns strings to be shown in the TagBox’s drop-down window.

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 enum Department { Motors, Electronics, Software }

    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 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’s items are populated with CustomType.ToString() values.

If your data is stored on a remote service and is loaded through a Web API, assign the data type to the component’s T parameter and use the CustomData property to implement data load logic.

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.

<DxTagBox Data="@Cities"
          AllowCustomTags="true"
          @bind-Tags="@Tags"
          @bind-Values="@Values"
          HideValues="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.

The table below lists API members related to the TagBox item collection:

Member	Description
Values	Provides access to the TagBox’s selected value/item collection.
ValuesChanged	Fires after a collection of selected values changes.
ValueFieldName	Specifies the data source field that populates values for the TagBox’s items.
DropDownVisible	Specifies the current state (displayed/hidden) of a drop-down window.
ShowDropDown()	Displays an editor’s drop-down window.

Tag Template

Use the TagTemplate property to customize a tag appearance. The template’s Context parameter ships with the following properties:

• IsCustom - Gets a value that specifies whether the processed tag is custom.
• Text - Gets the tag’s text.
• DataItem - Gets the tag’s bound data item.
• RemoveTagAction - Specifies the predefined action that removes the tag.

The code below demonstrates how to customize a tag appearance according to its type and text.

Razor

<DxTagBox Data="@DataSource"
          TextFieldName="@nameof(City.CityName)"
          TData="City"
          TValue="City"
          AllowCustomTags ="true"
          @bind-Tags="@Tags">
            <TagTemplate Context="tagInfo">
                @{
                    var styleMode = tagInfo.IsCustom ? ButtonRenderStyleMode.Contained: GetModeByID(tagInfo.DataItem.CountryId);
                    var style = tagInfo.IsCustom ? ButtonRenderStyle.Dark : ButtonRenderStyle.Primary;
                    <DxButton RenderStyle="@style"
                              RenderStyleMode="@styleMode"
                              Text="@tagInfo.Text"
                              style="display:inline-block">
                        @context
                        <span @onclick="@tagInfo.RemoveTagAction">&times;</span>
                    </DxButton>
                }
            </TagTemplate>
</DxTagBox>

@code {
    List<City> DataSource { get; set; }
    IEnumerable<string> Tags { get; set; }

    ButtonRenderStyleMode GetModeByID(int countryId) {
        switch (countryId) {
            case 0: return ButtonRenderStyleMode.Contained;
            case 1: return ButtonRenderStyleMode.Outline;
            default: return ButtonRenderStyleMode.Text;
        }
    }

    protected override void OnInitialized() {
        base.OnInitialized();
        DataSource = CityData.Cities;
        Tags = new List<string>() { "Los Angeles", "Tokyo", "Moscow" };
    }
}

City

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

Run Demo: TagBox - Tag Template

Multiple Columns

The TagBox can display data across multiple columns. To create columns, use DxListEditorColumn objects that include the following options for column customization:

• FieldName - Specifies the data source field that populates column items.
• Caption - Specifies the column header.
• Visible - Specifies the column visibility.
• VisibleIndex - Specifies the column display order.
• Width - Specifies the column width.

To format tag values, use the EditFormat property.

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

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

Run Demo: TagBox – Multiple Columns

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

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

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

Country

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

Run Demo: TagBox - Clear Button and Placeholder

Filter Data

The TagBox allows you to dynamically filter list items that contain the text typed into the editor. Use the FilteringMode property to specify the filter data criteria (Contains or StartsWith) or disable filtering.

<DxTagBox Data="@Data"
          @bind-Values="@Values"
          FilteringMode="DataGridFilteringMode.StartsWith">
</DxTagBox>

Run Demo: TagBox - Filter Modes

Size Modes

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

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

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

Virtual Scrolling

When virtual scrolling is activated (ListRenderMode is set to Virtual), the TagBox loads 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 code below 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.

Razor

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

EmailAddressesAttribute

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

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

Run Demo: TagBox - Validation

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 Window 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. List items are cut if they do not fit.

  

Note

When the TagBox loads items on demand (ListRenderMode is set to Virtual), the list width can change while users scroll items.

The following code sets the width of the drop-down list to the editor width.

Razor

@using BlazorApp.Data

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

@code {
    IEnumerable<Person> SelectedStaff { get; set; }
}

Person

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 enum Department { Motors, Electronics, Software }

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

Staff

using System;
using System.Collections.Generic;

namespace BlazorApp.Data {
    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; } }
    }
}

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

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(){
        //...
    }
}

Implements

IHandleEvent

IHandleAfterRender

IAsyncDisposable

IComponent

IDisposable

Inheritance

Show 11 items

Object

ComponentBase

DevExpress.Blazor.Base.DxAsyncDisposableComponent

DevExpress.Blazor.Base.DxDecoratedComponent

DxComponentBase

DxComponentBase<DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>

DevExpress.Blazor.Internal.DxEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>

DxDataEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>

DxResizableEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>

DxDropDownBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>

DxTagBox<TData, TValue>