JS Tutorial
- Overview
- Documents
Bootstrap Tags Input is a jQuery plugin providing a Twitter Bootstrap user interface for managing tags
Features
- Objects as tags
- True multi value
- Typeahead
- AngularJS directive included
- Designed for Bootstrap 2.3.2 and 3
Source: timschlechter.github.io
1. INCLUDE CSS AND JS FILES
<link rel="stylesheet" href="bootstrap-2.3.2/css/bootstrap.min.css"> <link rel="stylesheet" href="../dist/bootstrap-tagsinput.css"> <script src="bower_components/jquery/jquery.min.js"></script> <script src="bower_components/google-code-prettify-lite/prettify.js"></script> <script src="bootstrap-2.3.2/js/bootstrap.min.js"></script> <script src="../dist/bootstrap-tagsinput.js"></script>
2. EXAMPLES
Default
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" placeholder="Add tags" />
| statement | returns |
|---|---|
| $("input").val() |
"Amsterdam,Washington,Sydney,Beijing,Cairo" |
| $("input").tagsinput('items') |
["Amsterdam","Washington","Sydney","Beijing","Cairo"] |
True multi value
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() |
["Amsterdam","Washington","Sydney","Beijing","Cairo"] |
| $("select").tagsinput('items') |
["Amsterdam","Washington","Sydney","Beijing","Cairo"] |
Typeahead
<input type="text" value="Amsterdam,Washington" data-role="tagsinput" />
<script>
$('input').tagsinput({
typeahead: {
source: function(query) {
return $.getJSON('citynames.json');
}
}
});
</script>
| statement | returns |
|---|---|
| $("input").val() |
"Amsterdam,Washington" |
| $("input").tagsinput('items') |
["Amsterdam","Washington"] |
Objects as tags
<input type="text" />
<script>
$('input').tagsinput({
itemValue: 'value',
itemText: 'text',
typeahead: {
source: function(query) {
return $.getJSON('cities.json');
}
}
});
$('input').tagsinput('add', { "value": 1 , "text": "Amsterdam" });
$('input').tagsinput('add', { "value": 4 , "text": "Washington" });
$('input').tagsinput('add', { "value": 7 , "text": "Sydney" });
$('input').tagsinput('add', { "value": 10, "text": "Beijing" });
$('input').tagsinput('add', { "value": 13, "text": "Cairo" });
</script>
| statement | returns |
|---|---|
| $("input").val() |
"1,4,7,10,13" |
| $("input").tagsinput('items') |
[{"value":1,"text":"Amsterdam","continent":"Europe"},
{"value":4,"text":"Washington","continent":"America"},
{"value":7,"text":"Sydney","continent":"Australia"},
{"value":10,"text":"Beijing","continent":"Asia"},
{"value":13,"text":"Cairo","continent":"Africa"}]
|
Categorizing tags
<input type="text" />
<script>
$('input').tagsinput({
tagClass: function(item) {
switch (item.continent) {
case 'Europe' : return 'label label-info';
case 'America' : return 'label label-important';
case 'Australia': return 'label label-success';
case 'Africa' : return 'badge badge-inverse';
case 'Asia' : return 'badge badge-warning';
}
},
itemValue: 'value',
itemText: 'text',
typeahead: {
source: function(query) {
return $.getJSON('cities.json');
}
}
});
$('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" });
</script>
| statement | returns |
|---|---|
| $("input").val() |
"1,4,7,10,13" |
| $("input").tagsinput('items') |
[{"value":1,"text":"Amsterdam","continent":"Europe"},
{"value":4,"text":"Washington","continent":"America"},
{"value":7,"text":"Sydney","continent":"Australia"},
{"value":10,"text":"Beijing","continent":"Asia"},
{"value":13,"text":"Cairo","continent":"Africa"}]
|
3. OPTIONS
| 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 itemValue will be used.
$('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();
}
});
|
|
4. METHODS
| 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');
|
