DxTagBox<T> Class

A TagBox component.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.dll

Declaration

public class DxTagBox<T> :
    DxTagBoxBase<T>

Type Parameters

Name Description
T

The data item 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.

blazor_TagBox_Overview

NOTE

Online Demo: TagBox - Overview

Add TagBox to a Project

To add the <DxTagBox> component to an application, follow the steps below:

  1. Create and configure the application as described in the Create a New Blazor Application document.
  2. Add the <DxTagBox>...</DxTagBox> markup to your application.
  3. Bind the component to a data source.
  4. Configure the component (see the sections below).

Bind to Data

Use the Data property to bind the TagBox to an IEnumerable<T> data source synchronously. If the data source is large or requires access to a remote web service over slow networks, use the DataAsync property instead. It allows you to load data asynchronously and await completion without blocking application code execution.

The TagBox's item list is populated dynamically through data binding.

NOTE

The TagBox operates in bound mode only. Unbound mode is not supported.

<DxTagBox Data="@Cities"</DxTagBox>

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

Blazor_TagBox_Bind_To_Data

If you bind the TagBox to a data source that stores custom objects (IEnumerable<CustomType>), set the TextFieldName property. It specifies the custom object's field name that returns strings to be shown in the TagBox's drop-down window.

<DxTagBox Data="@DataSource"
          TextFieldName="Text">
</DxTagBox>

@code {
    IEnumerable<Person> DataSource;
}

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

To bind the TagBox to a data source that is not of the IEnumerable<T> type, assign the data source type to the component's T parameter and use the CustomData property to implement the 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.

Blazor_TagBox_Overview

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

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

    IEnumerable<string> tags = new List<string>() {
        "London",
        "New York",
        "Paris"
    };

    IEnumerable<string> Tags { get => tags; set { tags = value; InvokeAsync(StateHasChanged); } }

}

To specify tags in code, use the Tags property. To respond to the tag collection's changes, handle the TagsChanged event.

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

Member

Description

SelectedItems

Provides access to the TagBox's selected item collection.

SelectedItemsChanged

Fires after the selection changes.

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.

<DxTagBox Data="@DataSource"
          TextFieldName ="Data"
          AllowCustomTags ="true"
          @bind-Tags="@Tags">
            <TagTemplate Context="tagInfo">
                @{
                    string tagClass = tagInfo.IsCustom ? "btn btn-outline-secondary" : "btn " + tagInfo.DataItem.CssClass;
                    <span class=@tagClass>
                        <span>@tagInfo.Text</span>
                        <span @onclick="@tagInfo.RemoveTagAction">&times;</span>
                    </span>
                }
            </TagTemplate>
</DxTagBox>

@code {
    Option[] DataSource = null;

    IEnumerable<string> tags;
    IEnumerable<string> Tags { get => tags; set { tags = value; InvokeAsync(StateHasChanged); } }

    protected override void OnInitialized() {
        DataSource = new Option[] {
            new Option("Option 1", "btn-primary"),
            new Option("Option 2", "btn-success"),
            new Option("Option 3", "btn-primary"),
            new Option("Option 4", "btn-success"),
            new Option("Option 5", "btn-primary"),
            new Option("Option 6", "btn-success"),
            new Option("Option 7", "btn-primary")
        };
        tags = new List<string>() { "Option 2", "Option 5", "Custom Option", "Option 1", "Option 4" };
    }
}

Blazor_TagBox_Template

NOTE

Online Demo: TagBox - Tag Template

Null Text

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 in TagBox when its Tags property is set to null.

<DxTagBox Data="@DataSource"             
          NullText="Select an option..."
          ClearButtonDisplayMode="@DataEditorClearButtonDisplayMode.Auto" />
</DxTagBox>

Blazor_TagBox_Clear_Button

NOTE

Online Demo: TagBox - Null Text

Filter Data

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

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

Blazor_TagBox_Filter

NOTE

Online Demo: TagBox - Filter Modes

Validate Data

When you add the TagBox to Blazor's standard EditForm, you can use the ValidateBy property to validate the component's tags or selected items.

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:

After a user types an email address, the TagBox is outlined in red or green depending on the validation result.

<EditForm Model="@recipients" OnValidSubmit="@HandleValidSubmit" OnInvalidSubmit="@HandleInvalidSubmit">
    <DataAnnotationsValidator />
    <p>
        <label for="emails">Recipients:</label>
        <DxTagBox Id="emails"
                  NullText="Select email recipients"
                  Data="@Emails.DataSource"
                  AllowCustomTags="true"
                  ValidateBy="@TagBoxValidateBy.Tags"
                  @bind-Tags="@recipients.Data"
                  @bind-DropDownVisible="@DropDownVisible">
        </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");
    }
} 

blazor_TagBox_Validation

NOTE

Online Demo: TagBox - Validation

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"
            ListRenderMode="@ListRenderMode.Virtual">
</DxTagBox>
NOTE

Online Demo: TagBox - Virtual Scrolling

Read-Only State

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

<DxTagBox ReadOnly="true"> </DxTagBox>

Blazor_TagBox_ReadOnly

NOTE

Online Demo: TagBox - Read-Only Mode

Inheritance

Object
ComponentBase
DevExpress.Blazor.Base.DxDecoratedComponent
DxComponentBase
DxComponentBase<DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DevExpress.Blazor.Internal.DxEditorBase<T, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DxDropDownBase<T, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DxTagBoxBase<T>
DxTagBox<T>
See Also