stork-tags
v2.1.5
Published
The best and most efficient tags selector in the galaxy
Downloads
1
Keywords
Readme
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
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);