Overview

The TagBox is an editor that allows users to select multiple items (tags) from a predefined drop-down list. Users can also type in the edit box to filter list items that contain the search string. Users can also use the ARROW UP, ARROW DOWN, 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. To remove a tag, users can click its remove button or press Backspace.

The main TagBox API members are listed below.

  • Data - Specifies the data source that populates the editor’s list items.
  • TextFieldName - Specifies the data source’s field that supplies text for items.
  • Tags - Specifies the editor’s tags.
  • TagsChanged - Fires when the tag collection is changed.
  • Values - Specifies the drop-down list’s selected values.
  • ValuesChanged - Fires when the selected value collection is changed.

The TagBox component supports different size modes. To specify the component's size in code, use the SizeMode property. To apply different size modes, use the drop-down list in the demo card's header.

This demo illustrates how to bind the TagBox to a list of complex business objects.

Custom Tags

In this demo, the TagBox supports custom tags that are not stored in a bound data source (the AllowCustomTags property is set to true).

Item Values

The TagBox component provides access to item values. The value is assigned to the editor's edit value when a user selects an item from the drop-down list. To enable this access, set the ValueFieldName property to the name of the data source field that ships with values for the TagBox items.

If the ValueFieldName property is not specified, the TagBox component searches for a Value field in the data source and uses this field as a value field. Otherwise, values are not assigned to editor items.

To access values of the selected items, use the Values property. To track selection changes, use the ValuesChanged event or two-way synchronization as demonstrated in this module.

Multiple Columns

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

  • Caption - Specifies the column caption.
  • 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 an editor value, use the EditFormat property. This property allows you to format values displayed in both ordinary and multi-column TagBoxes. The {1} {2} format specifies that the editor value includes values of the following columns: Name (VisibleIndex = 1) and Surname (VisibleIndex = 2).

Null Text

This demo illustrates how to use the NullText property to display placeholder text in the TagBox when its value is null.

Set the ClearButtonDisplayMode property to Auto to display the Clear button when the TagBox has a non-null value. Users can click this button to clear the editor's value (set it to null).

Virtual Scrolling

Use the ListRenderMode property to specify how the TagBox loads the item list.

  • Entire - The TagBox loads the entire item list. Use this option for small item lists where scrolling should work instantly.
  • Virtual - The TagBox loads visible items only. Use this option to improve performance when the list contains to many items to load simultaneously.

In this demo, the ListRenderMode property is set to ListRenderMode.Virtual.

Filter Modes

Use the FilteringMode property to specify whether and how the TagBox filters list items when users type in the edit box.

  • Contains (Default) - The TagBox filters list items that contain the search string and highlights matches.
  • StartsWith - The TagBox filters list items that begin with the search string and highlights matches.
  • None - The TagBox does not filter list items.

In this demo, the filter mode is set to DataGridFilteringMode.StartsWith. To change the filter mode or disable filtering, use the Filtering Mode drop-down list.

Drop-Down List Width

Use the DropDownWidthMode property to specify the width of a drop-down list.

  • ContentOrEditorWidth (Default) - The list's width is equal to the width of the longest list item or the editor's width (whichever is larger).
  • ContentWidth - The list's width is equal to the width of the longest list item.
  • EditorWidth - The list's width is equal to the editor's width. List items are cut if they do not fit.

In this demo, ContentOrEditorWidth mode is used for both TagBox components. To change the width of their drop-down lists, use the Drop Down Width Mode option below.

Show Selected Items

In this demo, the TagBox displays selected items in the drop-down list. Set the HideSelectedItems property to false to enable this behavior.

Read-Only and Disabled Modes

In this demo, the TagBox displays values but does not allow users to change them. To implement this behavior, you can use any of the following modes:

  • Read-only mode. In this mode, you can use the keyboard to focus and navigate the component. Set the ReadOnly property to true to activate this mode.
  • Disabled mode. In this mode, the component cannot be focused or navigated. Set the Enabled property to false to activate this mode.

Tag Template

This demo illustrates how to use the TagTemplate property to customize tag's appearance.

The template’s Context parameter has the following properties:

  • DataItem - The tag’s bound data item (if the tag is not custom).
  • IsCustom -Returns whether the current tag is custom (not stored in the assigned data source).
  • RemoveTagAction - The predefined action that removes the tag.
  • Text - The tag’s text.

Validation

This demo illustrates how to add the TagBox to Blazor's standard EditForm component. This component allows data validation.

Use the TagBox’s ValidateBy property to specify whether to validate the editor’s tags or the drop-down list’s selected items. In this demo, this property is set to TagBoxValidateBy.Tags. The Tags property’s bound field is marked with the Required attribute and a custom data annotation attribute that validates email formats.

Users can select email recipients from a drop-down list or type email addresses in the edit box. 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.