DxTagBox<TData, TValue> Class

A TagBox component.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.dll

Declaration

public class DxTagBox<TData, TValue> :
    DxDropDownBase<TData, TagBoxJSInteropProxy>,
    IDataSourceSettings<TData>,
    IInputBase,
    IServiceProviderAccessor,
    IRequireSelfCascading,
    IDropDownWidthModeAccessor,
    ITagBoxJSInteropProxyServer,
    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.

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 an application. If you use Microsoft project templates, configure the application as described in this topic: Use Microsoft Templates..
  2. Add the <DxTagBox>...</DxTagBox> markup to your application.
  3. Bind the component to a data source (see details below).
  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"
    };
}

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.

@using BlazorApp.Data

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

TagBox Overview

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.

TagBox Overview

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

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

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.

<DxTagBox Data="@DataSource"
          TextFieldName ="Data"
          AllowCustomTags ="true"
          @bind-Tags="@Tags">
            <TagTemplate Context="tagInfo">
                @{
                    var style = tagInfo.IsCustom ? ButtonRenderStyle.Secondary : tagInfo.DataItem.Style;
                    var styleMode = tagInfo.IsCustom ? ButtonRenderStyleMode.Outline: ButtonRenderStyleMode.Contained;
                    <DxButton RenderStyle="@style" 
                              RenderStyleMode="@styleMode" 
                              Text="@tagInfo.Text" 
                              style="display:inline-block">
                        @context
                        <span @onclick="@tagInfo.RemoveTagAction">&times;</span>
                    </DxButton>
                }
            </TagTemplate>
</DxTagBox>

@code {
    Option[] DataSource { get; set; } = null;

    IEnumerable<string> Tags { get; set; }

    protected override void OnInitialized() {

        DataSource = new Option[] {
            new Option("Option 1", ButtonRenderStyle.Primary),
            new Option("Option 2", ButtonRenderStyle.Success),
            new Option("Option 3", ButtonRenderStyle.Primary),
            new Option("Option 4", ButtonRenderStyle.Success),
            new Option("Option 5", ButtonRenderStyle.Primary),
            new Option("Option 6", ButtonRenderStyle.Success),
            new Option("Option 7", ButtonRenderStyle.Primary)
        };

        Tags = new List<string>() { "Option 2", "Option 5", "Custom Option" };
    }
}

TagBox Template

NOTE

Online 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.
  • 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="@Persons.DataSource"
          @bind-Values="@SelectedPersons"
          EditFormat="{1} {2}">
    <DxListEditorColumn FieldName="Id" Width="50px" />
    <DxListEditorColumn FieldName="FirstName" />
    <DxListEditorColumn FieldName="LastName" />
</DxTagBox>

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

TagBox - Multiple Columns

NOTE

Online Demo: TagBox – Multiple Columns

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>

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>

TagBox Filter

NOTE

Online 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="@Persons.DataSource"
          TextFieldName="Text"
          @bind-Values="@SelectedPersons"
          SizeMode="SizeMode.Small"></DxTagBox>

<DxTagBox Data="@Persons.DataSource"
          TextFieldName="Text"
          @bind-Values="@SelectedPersons"
          SizeMode="SizeMode.Medium"></DxTagBox>

<DxTagBox Data="@Persons.DataSource"
          TextFieldName="Text"
          @bind-Values="@SelectedPersons"
          SizeMode="SizeMode.Large"></DxTagBox>

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

For more information, refer to 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"
          ListRenderMode="@ListRenderMode.Virtual">
</DxTagBox>
NOTE

Online 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:

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.

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

TagBox Validation

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

NOTE

Online Demo: TagBox - Validation

Read-Only State

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

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

Online Demo: TagBox - Read-Only Mode

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.

    TagBox Content or Editor Width

  • ContentWidth - The list width is equal to the width of the longest list item.

    TagBox Content Width

  • EditorWidth - The list width matches the editor. List items are cut if they do not fit.

    TagBox Editor Width

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 makes the width of the drop-down list equal to the editor width.

@using BlazorApp.Data

<DxTagBox Data="@Persons.DataSource"
          TextFieldName="Text"
          DropDownWidthMode="DropDownWidthMode.EditorWidth">
</DxTagBox>

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" DropDownDirection="DropDownDirection.Up" />

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

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

You can use HTML attributes to configure the TagBox.

<DxTagBox Data="@Strings" maxlength="10" autofocus> </DxTagBox>

Inheritance

Object
ComponentBase
DevExpress.Blazor.Base.DxDecoratedComponent
DxComponentBase
DxComponentBase<DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DevExpress.Blazor.Internal.DxEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DxResizableEditorBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DxDropDownBase<TData, DevExpress.Blazor.Internal.JSInterop.TagBoxJSInteropProxy>
DxTagBox<TData, TValue>
See Also