Description

The Tags component allows users to add and remove tags. It extends the ShadowComponent class.

Basic Usage

Use the Tags component to allow users to add and remove tags. Tags can be added by typing them into the input field and pressing Enter or Tab, or by pasting a comma-separated list of tags. You can delete a tag by clicking on it.

<k-tags>
  <label>Tags</label>
</k-tags>

Allowed Tags

Use the allowedTags attribute to specify a comma-separated list of allowed tags. Only these tags can be added.

<k-tags allowed-tags="tag1,tag2,tag3">
  <label>Allowed Tags</label>
</k-tags>

Disallowed Tags

Use the disallowedTags attribute to specify a comma-separated list of disallowed tags. These tags cannot be added.

<k-tags disallowed-tags="tag1,tag2,tag3">
  <label>Disallowed Tags</label>
</k-tags>

Suggestions

Provide a getSuggestions function to give the user inline autocomplete as they type. After a short pause (see the suggestion-debounce attribute) the component calls your function with the current query. The first returned suggestion that starts with what the user typed is shown as muted "ghost" text ahead of the cursor.

• Press Tab or Enter to save the suggested tag (or the typed text when no suggestion is showing).
• Press Backspace or Escape to cancel the suggestion. This does not delete any typed characters, so you can keep exactly what you typed and then press Tab/Enter to save it.

The getSuggestions function is called as getSuggestions(query, callback). Respond either by invoking the callback with an array of suggestions, or by returning an array or a Promise that resolves to one. This makes it easy to fetch suggestions from a server, such as the top tags that start with the typed string.

<k-tags id="imageTags">
  <label>Image Tags</label>
</k-tags>

const tags = document.getElementById('imageTags');
tags.suggestionDebounce = 300;
tags.getSuggestions = (query, callback) => {
  fetch(`/api/tags?startsWith=${encodeURIComponent(query)}&limit=50`).then(response => response.json()).then(suggestions => callback(suggestions));
};

tags.getSuggestions = async query => {
  const response = await fetch(`/api/tags?startsWith=${query}&limit=50`);
  return await response.json();
};

Disabled

Use the disabled attribute to prevent the user from adding or removing tags while still displaying the current value.

<k-tags disabled value="design,ui">
  <label>Tags</label>
</k-tags>

JavaScript Reference

Constructor

Extends ShadowComponent

new Tags()

Requirements

• ShadowComponent

Properties

value: string

A comma-separated list of tags. Syncs with the value attribute.

allowedTags: string

A comma-separated list of allowed tags. If specified, only these tags can be added. Syncs with the allowed-tags attribute.

disallowedTags: string

A comma-separated list of disallowed tags. If specified, these tags cannot be added. Syncs with the disallowed-tags attribute.

suggestionDebounce: number

The delay in milliseconds after the user stops typing before getSuggestions is called. Defaults to 300. Syncs with the suggestion-debounce attribute.

getSuggestions: (query: string, callback: (suggestions: string[]) => void) => void | string[] | Promise<string[]>

A function you provide to supply inline autocomplete suggestions. It is called with the current query and a callback. Respond by invoking the callback with an array of suggestions, or by returning an array or a Promise that resolves to one. When unset, no suggestions are shown. This is a JavaScript-only property and has no corresponding attribute.

disabled: boolean

When true, prevents the user from adding or removing tags. The current value is still displayed. The element appears at 50% opacity. Syncs with the disabled attribute.

Methods

addTag(tag): void

Adds a tag to the list of tags.

removeTag(tag): void

Removes a tag from the list of tags.

validateTags(): string

Validates the list of tags against the allowed and disallowed tags and returns the valid tags as a comma-separated string.

renderTags(): Promise<void>

Re-renders the tag elements in the component.

Events

change

Fired when the value changes. Detail contains { oldValue, newValue }.

addtag

Fired when a tag is added. Detail contains { tag }.

removetag

Fired when a tag is removed. Detail contains { tag }.

allowedtagschange

Fired when the allowed tags list changes. Detail contains { oldValue, newValue }.

disallowedtagschange

Fired when the disallowed tags list changes. Detail contains { oldValue, newValue }.