Skip to content

The best and most efficient tags selector in the galaxy

License

Notifications You must be signed in to change notification settings

storkjs/tags-input

Repository files navigation

tags-input

GitHub license GitHub issues Bower version

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

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