JavaScript API

Javascript API documentation

BulmaTagsInput is available as a JavaScript object, so you can use it directly.

// Instantiate on one element
new BulmaTagsInput(selector, options);

// Instantiate on multiple elements
BulmaTagsInput.attach(selector, options);

Arguments

  • selector: query String returning a single Node or directly a Node
  • options: see Options section
Main differences between methods are when using attach:

  • selector can be a query String returning a single Node or a NodeList, directly a Node or a NodeList
  • DOM modifications will be observed to detect any new element responding to the given selector to automatically instantiate BulmaTagsInput on them with the given option.

Access to BulmaTagsInput instance

Whatever the way you use to instantiate BulmaTagsInput, all element on which BulmaTagsInput is applied will now contains a new BulmaTagsInput function which will let you access to the instance at any time.

var inputTags = document.getElementById('input-tags');
new BulmaTagsInput(inputTags);

// Access to the BulmaTagsInput instance
var btiInstance = inputTags.BulmaTagsInput();

// Call BulmaTagsInput method
btiInstance.add('new Tag');

Options

Customize plugin behavior with options

You can easily manage the component behavior by passing an object of options to the constructor.

Options can be set either through JavaScript or directly on the DOM as dataset of the element.

Provide options when instanciating plugin. Options will be applied to all element provided (or found by the given selector).

BulmaTagsInput.attach('input[data-type="tags"], input[type="tags"], select[data-type="tags"], select[type="tags"]', {
    allowDuplicates: false,
	caseSensitive: true,
	clearSelectionOnTyping: false,
	closeDropdownOnItemSelect: true,
	delimiter: ',',
	freeInput: true,
	highlightDuplicate: true,
	highlightMatchesString: true,
	itemValue: undefined,
  	itemText: undefined,
	maxTags: undefined,
	maxChars: undefined,
	minChars: 1,
	noResultsLabel: 'No results found',
	placeholder: '',
	removable: true,
	searchMinChars: 1,
	searchOn: 'text',
	selectable: true,
	source: undefined,
	tagClass: 'is-rounded',
	trim: true
});

Add option directly to the element by using dataset attributes. This way, options can be specific to each element. These declaration will override any default option or option passed by the JavaScript instantiation. All you have to do is to use the kebab-case notation of option and declare it as a data attribute of the HTML Element.

<input type="tags" data-allow-duplicates="true" data-max-chars="10" data-min-chars="3" data-selectable="false">

Options list

All available option are described in the folowing table:

Option name Description Type Default value
allowDuplicates When true, the same tag can be added multiple times. Boolean false
caseSensitive When true, duplicate tags value check is case sensitive. Boolean true
clearSelectionOnTyping When true, tags will be unselected when new tag is entered. Boolean false
closeDropdownOnItemSelect When true, datalist will close automatically after an item have been selected. Boolean true
delimiter Multiple tags can be added at once. Delimiter is used to separate all tags. String ,
freeInput When true, tags can be entered manually. This option is useful with select Tags inputs. Set to false automatically when using on select element. Boolean true
highlightDuplicate When true, if allowDuplicates option if false then the already existing tag will be temporarly and visually identified as duplicate Boolean true
highlightMatchesString When true, identified matches strings when searching is highlighted. Boolean true
itemText When adding objects as tags, you can set itemText to the name of the property of item to use for a its tag’s text. When this options is not set, the value of itemValue will be used. String undefined
itemValue When adding objects as tags, itemValue must be set to the name of the property containing the item’s value. String undefined
maxTags When set, no more than the given number of tags are allowed to add. Integer undefined
maxChars Defines the maximum length of a single tag. Integer undefined
minChars Defines the minimum length of a single tag. Integer 1
noResultsLabel Empty dropdown label. String No results found
placeholder TagsInput placeholder text if original input doesn’t have one. String undefined
removable When true, tags are removable either using the associted delete button or backspace and delete keys. Boolean true
searchMinChars Defines the minimum length of input value before loading auto-complete. Integer 1
searchOn Defines on what dropdown item data do we search the entered value. Possible value: ‘value’ or ‘text’. String text
selectable When true, tags can be selected either by mouse click or using left or right arrow keys. Boolean true
source Source of data proposed in dropdown (used for auto-complete). Can be one of the following types:

  • Array of Strings / Objects
  • Function => Array of Strings / Objects
  • Promise => Array of Strings / Objects.
 undefined
tagClass Classname applied to each tag. String is-rounded
trim When true, automatically removes all whitespace around tags. Boolean true

API

Interact with the component

BulmaTagsInput : class
constructor

Instanciate the component based on the element provided and register the instance into BulmaTagsInput function of the element.

Parameters
Node element (can be a selector string - must target only one node - or a DOM node) on which attach the component
Component options. These options are merged with default options and options set via element data-attribute.
Example
const bulmaTagsInputElement = new BulmaTagsInput('#input-tags');

// Access to the BulmaTagsInput instance from DOM
const inputTagsElement = document.getElementById('input-tags');
if (inputTagsElement) {
  const bulmaTagsInputInstance = inputTagsElement.BulmaTagsInput();
}
attach : Array
constructor

Constructor shortcut with possibility to pass a String, a Node or a NodeList as a selector so we can instantciate multiple element at once. Return an array of all instances. Note that each instance is link to the related DOM node under BulmaTagsInput function.

Parameters
Selector (can be a selector string - can target multiple nodes - or a DOM node or a DOM nodes list) on which attach the component
Component options. These options are merged with default options and options set via element data-attribute.
Example
// Return an array of BulmaTagsInput instances (empty if no DOM node found)
const bulmaTagsInputInstances = BulmaTagsInput.attach();

// Loop into instances
bulmaTagsInputInstances.forEach(bulmaTagsInputInstance => {
    // Work with the instance
});
add : BulmaTagsInput
public

Add given item to the component

Parameters

Item to add. It can be one of the following type: String, Array.

You can provide multiple items at once by passing and Array of item or a string with multiple value delimited by delimiter option (default: comma).

Example
var inputTags = document.getElementById('myInputTag');

// Add one string item
inputTags.BulmaTagsInput().add('john');

// Add multiple string items in once by passing multiple values as a string delimited by comma
inputTags.BulmaTagsInput().add('john,jane');

// Add multiple string items as array
inputTags.BulmaTagsInput().add(['john', 'jane']);

// Add one object item
inputTags.BulmaTagsInput().add({
     "value": "1",
     "text": "John"
});

// Add multiple object items at once
inputTags.BulmaTagsInput().add([{
     "value": "1",
     "text": "John"
}, {
     "value": "2",
     "text": "Jane"
}]);
clearSelection : BulmaTagsInput
public

Unselect the current selected tag

Example
var inputTags = document.getElementById('myInputTag');

// Clear selection
inputTags.BulmaTagsInput().clearSelection();
flush : BulmaTagsInput
public

Shortcut to removeAll method

Example
var inputTags = document.getElementById('myInputTag');

// Remove all tags focus
inputTags.BulmaTagsInput().flush();
focus : BulmaTagsInput
public

Sets focus on the input

Example
var inputTags = document.getElementById('myInputTag');

// Set focus
inputTags.BulmaTagsInput().focus();
has : Boolean
public

Check if given item is present

Parameters
Item to find. It can be one of the following type: String, Array.
Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');

inputTags.BulmaTagsInput().has('john'); // return True
inputTags.BulmaTagsInput().has('jane'); // return False
hasValue : Boolean
public

Check if given value is present

Parameters
Single value to find.
Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add({
    "value": "john",
    "text": "John Doe"
});

inputTags.BulmaTagsInput().hasValue('john'); // return True
inputTags.BulmaTagsInput().hasValue('jane'); // return False
hasText : Boolean
public

Check if given text is present

Parameters
single Text to find in items.
Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add({
    "value": "john",
    "text": "John Doe"
});

inputTags.BulmaTagsInput().hasText('John Doe'); // return True
inputTags.BulmaTagsInput().hasValue('Jane Doe'); // return False
indexOf : Integer
public

Get index of given item

Parameters
Item to find. It can be one of the following type: String, Array.
Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');

inputTags.BulmaTagsInput().indexOf('john'); // return 0
inputTags.BulmaTagsInput().has('jane'); // return -1
input : HTMLElement
public

Get the internal input element

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');

inputTags.BulmaTagsInput().input();
items : Array
public

Get all added items

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');

inputTags.BulmaTagsInput().item(); // return ['john']
remove : BulmaTagsInput
public

Remove given items

Parameters

Item to add. It can be one of the following type: String, Array.

You can provide multiple items at once by passing and Array of item or a string with multiple value delimited by delimiter option (default: comma).

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');

inputTags.BulmaTagsInput().remove('john');
removeAll : BulmaTagsInput
public

Remove all tags at once

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');
inputTags.BulmaTagsInput().add('jane');

inputTags.BulmaTagsInput().items(); // return ['john', 'jane']

inputTags.BulmaTagsInput().removeAll();
inputTags.BulmaTagsInput().items(); // return [] (empty array)
removeAtIndex : BulmaTagsInput
public

Remove item at given index.

Parameters
Index of the item to remove.
Should current selection be cleared (default: true)
Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');

inputTags.BulmaTagsInput().items(); // return ['john']

inputTags.BulmaTagsInput().removeAtIndex(0);
inputTags.BulmaTagsInput().items(); // return [] (empty array)
select : BulmaTagsInput
public

Select given item

Parameters

Item to add. It can be one of the following type: String, Array.

You can provide multiple items at once by passing and Array of item or a string with multiple value delimited by delimiter option (default: comma). If a list of items is passed then each item will be selected one by one and at the end only the last existing item from the list will be selected at the end.

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');
inputTags.BulmaTagsInput().add('jane');

inputTags.BulmaTagsInput().select('john'); // Tag containing 'john' value now have is-selected class
selectAtIndex : BulmaTagsInput
public

Select tag at given index

Parameters
Index of the item to select.
Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');
inputTags.BulmaTagsInput().add('jane');

inputTags.BulmaTagsInput().selectAtIndex(0); // Tag containing 'john' value now have is-selected class
selected : Integer
public

Get the current selected item

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');
inputTags.BulmaTagsInput().add('jane');

inputTags.BulmaTagsInput().selectAtIndex(0);
var selectedItem = inputTags.BulmaTagsInput().selected;
// selectedItem = 'john'
selectedIndex : String|Object
public

Get the current selected item index

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');
inputTags.BulmaTagsInput().add('jane');

inputTags.BulmaTagsInput().selectAtIndex(0);
var selectedItem = inputTags.BulmaTagsInput().selectedIndex;
// selectedItem = 0
value : String|Array
public

Get component value

Example
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().add('john');
inputTags.BulmaTagsInput().add('jane');

var value = inputTags.BulmaTagsInput().value;
// value = "john,jane"

// If component has been instantiated on a multiple select element then a real array is returned
// value = ["john", "jane"]
_build
private

Build TagsInput DOM elements

_bindEvents
private

Bind all events listener

_caretAtStart : Boolean
private

Determine if input caret it at the start of the input or not.

_checkLength : Boolean
private

Check value length constraint if option activated

Parameters
Item data
_createDropdownItem
private

Create a new dropdown item based on given item data

Parameters
Item data
_createTag
private

Create a new tag and add it to the DOM

Parameters
Item data
_emptyDropdown
private

Remove all dropdown items except the empty title

_filterDropdownItems
private

Filter Dropdown items to be compliant with already selected items and current input value Filtering is made on Text by default (can be changed with option)

Parameters
String to search for to filter items
_highlightMatchesInString
private

Find needle into a string and wrap it with HTML tag

Parameters
String in which search item
String to search for
_init
private

Initialize component, define internal variables and elements.

_onDocumentClick
private

Listen document click events to manage dropdown visibility. It prevents dropdown to be hidden when the click occurs inside the TagsInput component.

Parameters
DOM Event Object reference
_onDropdownItemClick
private

Listener handling dropdown item click and call add method.

Parameters
DOM Event Object reference
_onInputChange
private

Listen to internal input change event and filter dropdonw items.

Parameters
DOM Event Object reference
_onInputClick
private

Listen to internal input click event and display dropdown if it is relevant.

Parameters
DOM Event Object reference
_onInputFocusIn
private

Add is-focused class to the TagsInput container when the internal input get focus.

Parameters
DOM Event Object reference
_onInputFocusOut
private

Remove is-focused class from the TagsInput container when the internal input lost focus.

Parameters
DOM Event Object reference
_onInputKeyDown
private

Parameters
DOM Event Object reference
_onInputKeyPress
private

Parameters
DOM Event Object reference
_onOriginalInputChange
private

Listen to original input change event to automatically update tags.

Parameters
DOM Event Object reference
_onTagClick
private

Listen to tags click events to handle tag selection.

Parameters
DOM Event Object reference
_onTagDeleteClick
private

Listen to tag delete button click event to handle tag deletion.

Parameters
DOM Event Object reference
_openDropdown
private

Open dropdown element

_propagateChange
private

Propagate internal input changes to the original input

_trim
private

Trim item is trim option is set to true. This function handle both string and object items.

_updateDropdown
private

Update dropdown items based on context.

_updateSelectOptions
private

Update original select option based on given item.

Parameters
Item data

Events

This component provides some events you can listen to to react on state changes.

Event name Description Example
before.add Trigerred before adding new tag. The concerned item is passed as parameter. You can modify the item before its treatment by returning the new item data or prevent tag to be added by returning false. 
var inputTags = document.getElementById('myInputTag');
// Example to capitalize a string item
inputTags.BulmaTagsInput().on('before.add', function(item) {
    return item.charAt(0).toUpperCase() + item.slice(1);
});

// Example to accept string with only letters
inputTags.BulmaTagsInput().on('before.add', function(item) {
    return item.value.match(/^[A-Za-z]+$/);
});
after.add Triggered once a tag has been added. The added item and the related tag are passed in an object as parameter. 
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().on('after.add', function(data) {
    console.log(data.item);
    console.log(data.tag);
});
before.remove Triggered before removing a tag. The concerned item is passed as parameter. You can prevent deletion by returning false. 
var inputTags = document.getElementById('myInputTag');
// Prevent all tags from being deleted
inputTags.BulmaTagsInput().on('before.remove', function(item) {
    return false;
});
after.remove Triggered once a tag has been removed. The removed item is passed as parameter. 
var inputTags = document.getElementById('myInputTag');
// Log all string items removes in the console
inputTags.BulmaTagsInput().on('after.remove', function(item) {
    console.log(item + " has been removed";
});
before.flush Triggered before flushing items. Items array is passed as parameter. 
var inputTags = document.getElementById('myInputTag');
// Log all string items concerned by the flush
inputTags.BulmaTagsInput().on('before.flush', function(items) {
    items.forEach(function(item) {
        console.log(item + " will be flush";
    });
});
after.flush Triggered after flushing items. 
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().on('after.flush', function(items) {
    // items should be an empty array
});
before.select Triggered before selecting an item. The concerned item and related tag are passed in an Object as parameter. 
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().on('before.select', function(data) {
    console.log(data.item);
    console.log(data.tag);
});
after.select Triggered once an item has been selected. The concerned item and related tag are passed in an Object as parameter. 
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().on('after.select', function(data) {
    console.log(data.item);
    console.log(data.tag);
});
before.unselect Triggered before unselect an item. The concerned item and related tag are passed in an Object as parameter. 
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().on('before.unselect', function(data) {
    console.log(data.item);
    console.log(data.tag);
});
after.unselect Triggered once an item has been unselected. The concerned item and related tag are passed in an Object as parameter. 
var inputTags = document.getElementById('myInputTag');
inputTags.BulmaTagsInput().on('after.select', function(data) {
    console.log(data.item);
    console.log(data.tag);
});