stork-tags

tags-input

What is it? The best and most efficient tags selector in the galaxy. Has the most essential features without redundant bloat.

Why? Because all other tags-input or multi-select components are too opinionated or too restricted to <select> style.

TOC

• Usage
• Options
• Methods
• Events
• Code Example
• Demo

Usage

Initiate the Tags Input with new StorkTagsInput(options). This will return a tags object for further adjusting the tags-input later.

Options

element: the HTML DOM Element that will hold the tags-input. Example: { element: document.getElementById('my_autocomplete') }

suggestionsHandler: a Function handling what suggestions/autocomplete results are shown according to the user's input. Example:

var suggestions_handler = function suggestions_handler(text, chosenTags, callback) {
  if(text.indexOf('dollar') > -1) {
    callback([{
      label: 'Currencies',
      field: 'currencies',
      items: [
        { label: 'US Dollar', value: 'USD' },
        { label: 'Australian Dollar', value: 'AUD' },
        { label: 'Canadian Dollar', value: 'CAD' },
        { label: 'Singapore Dollar', value: 'SGD' }
      ]
    }]);
    return;
  }
 
  callback([]);
};

inputMinWidth [optional]: the minimum width the search input is allowed to be. defaults to 60px. Example: { inputMinWidth: 75 }

rechooseRemove [optional]: whether re-choosing from the suggestions list an item that is already chosen will remove this item from the tags. defaults to false. Example: { rechooseRemove: true }

placeholder [optional]: The placeholder text that will be displayed on an empty tags input. Example: { placeholder: 'Type here..' }

persistentPlaceholder [optional]: The placeholder text always be displayed. Example: { persistentPlaceholder: true }

multiline [optional]: Enables the tags container to become multiline as the number of tags exceed the line width: { multiline: true }

showGroups [optional]: Enables to show tag's group inside the tag: { showGroups: true }

maxlength [optional]: The maximum length of characters the user is allowed to type per tag. defaults to 50. Example: { maxlength: 65 }

maxTags [optional]: The maximum allowed number of chosen tags. Beyond this amount the suggestions handler will not be triggered at all. Example: { maxTags: 7 }

persistentSuggestions [optional]: After adding or removing a tag, the default suggestions will keep being triggered. Example: { persistentSuggestions: true }

multiValues [optional]: Can allow or disallow multiple values per tag. defaults to true. Example: { multiValues: false }

Methods

addTag(tagObj): adds a new tag to the chosen tags list. arguments: tagObj {object} - tagObj.value, tagObj.label, tagObj.groupField (optional), tagObj.groupLabel (optional).

removeTag(index): remove a tag from the chosenTags. arguments: index {integer} - the position of the tag in the chosenTags array.

addEventListener(type, listener, optionsUseCapture): adds an event listener to the DOM Element of the tags-input. arguments: type {string}, listener {function}, optionsUseCapture {boolean|object}. Example:

myTags.addEventListener("tag-added", function(e) {
  console.log('added tag:', e.detail); // logs: {obj: {tag values}, index: #}
}, false);

Events

tag-added: when a new tag has been chosen and added to the list. this event has a detail containing the tag JS object, the specific value added to this tag and its index in the array. Example:

myTags.addEventListener("tag-added", function(e) {
  console.log('added tag:', e.detail); // logs: {obj: {values: ['hi'], labels: ['hi'], groupField: '', groupLabel: '', elm: LI}, value: 'hi', index: 0}
}, false);

tag-removed: when a tag is removed the list or a value is removed from a tag. this event has a detail containing the tag JS object and its previous index in the array. if only a value was removed but the tag still remains with other values then also a 'value' property along the detail object. Example:

myTags.addEventListener("tag-removed", function(e) {
  console.log('tag removed:', e.detail); // logs: {obj: {values: ['hi'], labels: ['hi'], groupField: '', groupLabel: '', elm: LI}, index: 0}
  console.log('tag value removed:', e.detail); // logs: {obj: {values: ['hi','you'], labels: ['hi','you'], groupField: '', groupLabel: '', elm: LI}, value: 'there', index: 0}
}, false);

all-tags-removed: when all tags are removed at once. this event has a detail contains all of the removed tags. Example:

myTags.addEventListener("all-tags-removed", function(e) {
  console.log('all tags removed:', e.detail); // logs: {removedTags: [
    {values: ['hi'], labels: ['hi'], groupField: '', groupLabel: '', elm: LI},
    {values: ['you'], labels: ['you'], groupField: '', groupLabel: '', elm: LI}
  ]}
}, false);

Code Example

<div id="tagsInput" style="width: 400px; height: 32px;"></div>

var i, j, regex;
var suggestions_handler = function suggestions_handler(text, chosenTags, callback) {
  if(text.indexOf('dollar') > -1) {
      callback([{
        label: 'Currencies',
        field: 'currencies',
        items: [
          { label: 'US Dollar', value: 'USD' },
          { label: 'Australian Dollar', value: 'AUD' },
          { label: 'Canadian Dollar', value: 'CAD' },
          { label: 'Singapore Dollar', value: 'SGD' }
        ]
      }]);
      return;
    }
 
    callback([]);
};
 
var testTags = new StorkTagsInput({
  element: document.getElementById('tagsInput'),
  suggestionsHandler: suggestions_handler,
  rechooseRemove: true,
  inputMinWidth: 70
});
 
testTags.addTag({ value: 'AUD', label: 'Australian Dollar', groupField: 'currencies', groupLabel: 'Currencies' });
 
testTags.addEventListener('tag-added', function(e) {
  console.log('added tag:', e.detail);
}, false);
testTags.addEventListener('tag-removed', function(e) {
  console.log('removed tag:', e.detail);
}, false);

Demo

View demo on plunker