Components / Library version 3.26.0

Tag Input

The Tag Input component allows a user to select a list of tags. Options can be specified by the developer or, if allowed, created by the user (dropdown variant only).

The component consists of an input area consisting of a tag area and a search field and, depending on the variant, a dropdown list or a table underneath the input. The tag area displays all currently selected tags and allows the user to remove tags. The search field allows users to filter the displayed options and eventually to create new tags.

In the dropdown variant the dropdown displays help text and all selectable options. The table variant allows to display more data, for instance people's names, email and role. The table variant's input field should always remain in view when interacting with the component, see the Notes tab for more information.

Properties Examples Events Accessibility Notes

* Required property

label *
string
A description for the Tag Input. Required even if the label-position is set to none (for accessibility reasons).
error-message
string
Sets the Tag Input in error state and displays a custom error message, e.g. the required-field error "Please select at least one tag"
info
string
Sets the info text displayed under the component.
label-position
top | left | none
Defaults to top. Set to none if no label should be displayed.
max-tags
number
The maximum number of tags that can be selected.
message-config
string: json
Replaces component messages with those provided. Should only be used to change the term "tag" to something more contextual like "lead". For more information about the object keys and default messages, see section below.
placeholder
string
Sets the placeholder text present in the search field. Defaults to the following possibilities depending on component configuration: Add a new tag, Search and select a tag, or Add or search for a tag
required-field
boolean
Displays an asterisk next to the label indicating that the field is required. Note: this must be used in conjunction with the label property.
selected-tags
string: csv
A comma-separated string of all tags that will load as pre-selected. In the dropdown variant, this is the option text itself. In the table variant, list the id of each <wm-tag-input-table-row>
tag-input-type
dropdown | table
Sets the variant of the component. Defaults to dropdown.

Dropdown variant

add-new
boolean
Determines the user's ability to add new tags. Defaults to true.
character-limit
number
Sets the maximum character limit for the search field. Defaults to 50.
options
string: csv
A comma-separated list of all options that populate the dropdown.

Table variant

col-headers *
string: csv
A comma-separated list of the table headers. The number of items determines the number of columns.
col-widths
string: csv
A comma-separated list of the widths of the columns. If a value is left blank, the column will fill the remaining space.
col-wrap
string: csv
A comma-separated list for the text wrapping rule for each column. Can be either "wrap" or "trunc" (truncate). Defaults to "wrap" (so if the property is absent all columns' text will wrap). If provided less values than there are columns, the last columns will wrap (so "trunc" is equivalent to "trunc, wrap, wrap, wrap" if 4 columns have been specified)

For wm-tag-input-table-row

id *
string
Unique id. Pass this reference to wm-tag-input's selected-tags to preselect rows.
col1 | col2 | col3 | col4
string
Values for each column.
locked
boolean
Disables the table row (displays a lock icon on the tag and on the row).

Properties of the object passed to message-config

addNewHelpText
string
Appears in the dropdown when component has selectable tags. Defaults to “Press the Enter or Comma key to add a new tag”
maxTagsReached
string
Appears towards the bottom of the component if the maximum number of tags has been reached. Defaults to “No more tags can be added because the limit has been reached”
selectionHelpText
string
Appears in the dropdown when the user is able to add new tags. Defaults to "Search and select a tag."
tagAreaInstructions
string
Screen reader instructions read when focusing the selected tag area. Sentence is preceded by the component's label. Defaults to “tag selection. Press Backspace or Delete to remove a tag”
tagsAdded
string
Appears towards the bottom of the component indicating how many tags are currently selected. Defaults to “Tags added”

Usage in HTML

Edit the code below to see changes reflected in the example above.

Javascript Sample

Example code for functionality.

Usage in Elm

Code generated from HTML.
wmTagInputChanged
Emitted when the selected tags have changed. The event.detail is an object containing two keys: value is all the currently selected tags, and tagChanged is the tag which triggered the event. For the dropdown variant, tags are represented by their exact string. For the table variant, tags are represented a reference to the corresponding wm-tag-input-row.

Keyboard Support

Tag Area

Key Function
Left Arrow Right Arrow Navigate through the tag list.
Backspace Delete Remove the currently focused tag. If this tag was added by the user, removes the corresponding list item from the dropdown.

Search Field

Key Function
Down Arrow Up Arrow If the dropdown is closed, re-opens it. If the dropdown is open, begin navigating the dropdown. If the first list item is reached, Up will focus the search field.
Escape If the dropdown is open, closes it.
Key Function
Up Arrow Down Arrow Navigate through the list items.
Escape Stops navigating the dropdown and returns focus to the search field.

Table

Key Function
Up Arrow Down Arrow Navigate through the table rows.
Left Arrow Right Arrow Navigate through the row's cells.
  • Tag Inputs have a max-height of 80vh. This ensures that in the Table variant, where the content might exceed the height of the screen, the table itself scrolls rather than the whole component. The input field should always remain in view while the user is interacting with the component. If different height requirements are needed, the max-height value can be overwritten or the Tag Input can be given with a fixed height. See the Example tab for an illustration.
  • The component consists of two tab stops, the tag area and the search field. If no tags are selected only the search field will be present.
  • Duplicate tags cannot be added when using the dropdown variant.
  • The dropdown options are sorted alphabetically.
  • If a user-added tag is removed, its corresponding dropdown option will be removed as well.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.