Components / Library Version 5.4.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.

Properties

Examples

API

Accessibility

Notes

* 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.