Components / Library Version 4.9.0

Tag Input

The Tag Input component allows a user to select a list of tags. The options can be shown either in a dropdown or in a table. A search field allows the user to filter the options and, if allowed, to create new tags (dropdown variant only).

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.

Options are specified with the <wm-tag-option> component.

PropertiesExamplesAPIAccessibilityNotes

* Required property

label *
string
A description for the Tag Input. Required even if the label-position is set to none (for screen reader users).
error-message
string
Sets the Tag Input in error state and displays a custom error message.
help-text
string
This property overrides the component default messages. In the dropdown variant it replaces the message at the top of the dropdown ("Search and select a tag." and, if applicable, "Press the Enter or Comma key to add a new tag."). In the table variant when max-tags is set, it replaces the message under the input ("Tags added: x/y" and, when applicable, " - No more tags can be added because the limit has been reached."
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. Note: left is not supported by the Table variant.
max-tags
number
Adds a box below the input with the message: "Tags added: x/y". When the maximum number of tags is reached, the message will be "Tags added: x/y - No more tags can be added because the limit has been reached." This message can be changed with the help-text property. The component doesn't enforce this limit and will still emit events if the limit is reached and the user selects a tag.
placeholder
string
Sets the search field's placeholder text. Depending on context it could be for instance: 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.
tag-area-instructions
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”
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. This limit is enforced by the component, which will display the number of characters and announce the limitation to screen reader users.

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-option

col1 | col2 | col3 | col4
string
Values for each column.
locked
boolean
When locked, the option is selected (shown as a tag) and cannot be deselected (the table row is disabled and a lock icon is shown next to it).
selected
boolean
Selects the option in the dropdown or table.

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.

wmTagOptionSelected
Emitted by wm-tag-option when the user selects an option.
wmTagOptionDeselected
Emitted by wm-tag-option when the user deselects an option (either clicking on a selected row in the table or removing a tag).
wmTagInputTagAdded
Emitted by wm-tag-input when the user adds a new option. ev.detail contains the string typed by the user.

Keyboard Support

Tag Area

Key Function
Left Arrow Right Arrow Navigate through the tag list.
Backspace Delete Removes the currently focused tag. Handle the removal with the event wmTagInputTagRemoved. If the tag was initially added by the user, the option should also be removed from the list by deleting the corresponding wm-tag-option element.

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.
Enter Dropdown variant: If user has typed and add-new is set to true, adds the user input as a new tag and as a (selected) option in the dropdown. Handle this action with the event wmTagInputTagAdded.
Key Function
Up Arrow Down Arrow Navigate through the list items.
Escape Stops navigating the dropdown and returns focus to the search field.
Enter Adds the currently focused option as a new tag. Handle this action by setting the wm-tag-option's selected property to true with the event wmTagInputTagAdded.

Table

Key Function
Up Arrow Down Arrow Navigate through the table rows.
Left Arrow Right Arrow Navigate through the row's cells.
Enter Adds the currently focused row as a new tag. Handle this action by setting the wm-tag-option's selected property to true with the event wmTagInputTagAdded.
  • 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.
  • In the dropdown variant, when the user can add tags (add-new="true"), the component detects duplicate entries in order to properly announce the duplicate entry to screen reader users. It does not emit the wmTagInputTagAddes event.