jQuery plugin providing a Twitter Bootstrap user interface for managing tags
Just add data-role="tagsinput"
to your input field to automatically change it to a tags input field.
<input type="text" value="Amsterdam,Washington,Sydney,Beijing,Cairo" data-role="tagsinput" />
statement | returns |
---|---|
$("input").val() | |
$("input").tagsinput('items') |
Use a <select multiple />
as your input element for a tags input, to gain true multivalue support. Instead of a comma separated string, the values will be set in an array. Existing <option />
elements will automatically be set as tags. This makes it also possible to create tags containing a comma.
<select multiple data-role="tagsinput"> <option value="Amsterdam">Amsterdam</option> <option value="Washington">Washington</option> <option value="Sydney">Sydney</option> <option value="Beijing">Beijing</option> <option value="Cairo">Cairo</option> </select>
statement | returns |
---|---|
$("select").val() | |
$("select").tagsinput('items') |
<input type="text" value="Amsterdam,Washington" data-role="tagsinput" /> <script> $('input').tagsinput(); // Adding custom typeahead support using http://twitter.github.io/typeahead.js $('input').tagsinput('input').typeahead({ prefetch: 'citynames.json' }).bind('typeahead:selected', $.proxy(function (obj, datum) { this.tagsinput('add', datum.value); this.tagsinput('input').typeahead('setQuery', ''); }, $('input'))); </script>
statement | returns |
---|---|
$("input").val() | |
$("input").tagsinput('items') |
You can set a fixed css class for your tags, or determine dynamically by provinding a custom function.
<input type="text" /> <script> $('input').tagsinput({ tagClass: function(item) { switch (item.continent) { case 'Europe' : return 'label label-primary'; case 'America' : return 'label label-danger label-important'; case 'Australia': return 'label label-success'; case 'Africa' : return 'label label-default'; case 'Asia' : return 'label label-warning'; } }, itemValue: 'value', itemText: 'text' }); $('input').tagsinput('add', { "value": 1 , "text": "Amsterdam" , "continent": "Europe" }); $('input').tagsinput('add', { "value": 4 , "text": "Washington" , "continent": "America" }); $('input').tagsinput('add', { "value": 7 , "text": "Sydney" , "continent": "Australia" }); $('input').tagsinput('add', { "value": 10, "text": "Beijing" , "continent": "Asia" }); $('input').tagsinput('add', { "value": 13, "text": "Cairo" , "continent": "Africa" }); // Adding custom typeahead support using http://twitter.github.io/typeahead.js $('input').tagsinput('input').typeahead({ valueKey: 'text', prefetch: 'cities.json', template: '<p>{{text}}</p>', engine: Hogan }).bind('typeahead:selected', $.proxy(function (obj, datum) { this.tagsinput('add', datum); this.tagsinput('input').typeahead('setQuery', ''); }, $('input'))); </script>
statement | returns |
---|---|
$("input").val() | |
$("input").tagsinput('items') |
option | description | |
---|---|---|
tagClass |
Classname for the tags, or a function returning a classname $('input').tagsinput({ tagClass: 'big' }); $('input').tagsinput({ tagClass: function(item) { return (item.length > 10 ? 'big' : 'small'); } }); |
|
itemValue |
When adding objects as tags, itemValue must be set to the name of the property containing the item's value, or a function returning an item's value. $('input').tagsinput({ itemValue: 'id' }); $('input').tagsinput({ itemValue: function(item) { return item.id; } }); |
|
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. You may also provide a function which returns an item's value. When this options is not set, the value of $('input').tagsinput({ itemText: 'label' }); $('input').tagsinput({ itemText: function(item) { return item.label; } }); |
|
confirmKeys |
Array of keycodes which will add a tag when typing in the input. (default: [13], which is ENTER) $('input').tagsinput({ confirmKeys: [13, 44] }); |
|
maxTags |
When set, no more than the given number of tags are allowed to add (default: undefined). When maxTags is reached, a class 'bootstrap-tagsinput-max' is placed on the tagsinput element. $('input').tagsinput({ maxTags: 3 }); |
|
freeInput |
Allow creating tags which are not returned by typeahead's source (default: true)
This is only possible when using string as tags. When itemValue option is set, this option will be ignored.
$('input').tagsinput({ typeahead: { source: ['Amsterdam', 'Washington', 'Sydney', 'Beijing', 'Cairo'] }, freeInput: true }); |
|
typeahead |
Object containing typeahead specific options |
|
source |
An array (or function returning a promise or array), which will be used as source for a typeahead. $('input').tagsinput({ typeahead: { source: ['Amsterdam', 'Washington', 'Sydney', 'Beijing', 'Cairo'] } }); $('input').tagsinput({ typeahead: { source: function(query) { return $.get('http://someservice.com'); } } }); |
|
onTagExists |
Function invoked when trying to add an item which allready exists. By default, the existing tag hides and fades in. $('input').tagsinput({ onTagExists: function(item, $tag) { $tag.hide.fadeIn(); } }); |
method | description |
---|---|
add |
Adds a tag $('input').tagsinput('add', 'some tag'); $('input').tagsinput('add', { id: 1, text: 'some tag' }); |
remove |
Removes a tag $('input').tagsinput('remove', 'some tag'); $('input').tagsinput('remove', { id: 1, text: 'some tag' }); |
removeAll |
Removes all tags $('input').tagsinput('removeAll'); |
focus |
Sets focus in the tagsinput $('input').tagsinput('focus'); |
input |
Returns the tagsinput's internal <input />, which is used for adding tags. You could use this to add your own typeahead behaviour for example. var $elt = $('input').tagsinput('input'); |
refresh |
Refreshes the tags input UI. This might be usefull when you're adding objects as tags. When an object's text changes, you'll have to refresh to update the matching tag's text. $('input').tagsinput('refresh'); |
destroy |
Removes tagsinput behaviour $('input').tagsinput('destroy'); |
event | description |
---|---|
beforeItemAdd |
Triggered just before an item gets added. Example:
$('input').on('beforeItemAdd', function(event) { // event.item: contains the item // event.cancel: set to true to prevent the item getting added }); |
itemAdded |
Triggered just after an item got added. Example:
$('input').on('itemAdded', function(event) { // event.item: contains the item }); |
beforeItemRemove |
Triggered just before an item gets removed. Example:
$('input').on('beforeItemRemove', function(event) { // event.item: contains the item // event.cancel: set to true to prevent the item getting removed }); |
itemRemoved |
Triggered just after an item got removed. Example:
$('input').on('itemRemoved', function(event) { // event.item: contains the item }); |