Components / Library version 3.13.0

Tag Input

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

The component consists of a tag area, an input area, and a dropdown list. The tag area displays all currently selected tags and allows the user to remove tags. The input area allows users to filter the displayed options or create new tags. The dropdown displays help text and all selectable options.

Properties Examples Events Accessibility Notes

* Required property

label *
string
A description for the input. Required even if the label-position is set to none (for accessibility reasons).
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 input field. Defaults to 50.
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.
options
string: csv
A comma-separated string of all options that populate the dropdown.
placeholder
string
Sets the placeholder text present in the input 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
selected-tags
string: csv
A comma-separated string of all tags that will load as pre-selected. As the user selects tags, the value will be updated to reflect the current selection.

Usage in HTML

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

Usage in Elm

Code generated from HTML.
wmTagInputChanged
Emitted when the selected tags have changed. The event detail contains a list of all selected tags.

Keyboard Support

Tag Area

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

Input Area

Key Function
Down ArrowUp 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 input field.
Escape If the dropdown is open, closes it.

Dropdown

Key Function
Up ArrowDown Arrow Navigate through the list items.
Escape Stops navigating the dropdown and returns focus to the input area.
  • The component consists of two tab stops, the tag area and the input area. If no tags are selected only the input area will be present.
  • Duplicate tags cannot be added.
  • List items are sorted alphabetically.
  • If a user-added tag is removed, it's corresponding list item 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.