Bootstrap Tags Input

jQuery plugin providing a Twitter Bootstrap user interface for managing tags

Examples

Markup

Just add data-role="tagsinput" to your input field to automatically change it to a tags input field.

Show code 
<input type="text" value="Amsterdam,Washington,Sydney,Beijing,Cairo" data-role="tagsinput" placeholder="Add tags" />
statementreturns
$("input").val()
$("input").tagsinput('items')

        


        

          
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.
          

          

            
          

          

            

              

                
                  Show code
                
              

              

                

                  
<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>

                

              

            

          

           
statementreturns
$("select").val()
$("select").tagsinput('items')

        

       
        

          
Typeahead

          

            
          

           

            

              

                
                  Show code
                
              

              

                

                  
<input type="text" value="Amsterdam,Washington" data-role="tagsinput" />
<script>
$('input').tagsinput({
  typeahead: {
    source: function(query) {
      return $.getJSON('citynames.json');
    }
  }
});
</script>

                

              

            
                  
          

          
statementreturns
$("input").val()
$("input").tagsinput('items')

        


        

          
Objects as tags

          

            Instead of just adding strings as tags, bind objects to your tags. This makes it possible to set id values in your input field's value, instead of just the tag's text.
          

          

            
          

          

            

              

                
                  Show code
                
              

              

                

                  
<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>

                

              

            

          

          
statementreturns
$("input").val()
$("input").tagsinput('items')

        


        

          
Categorizing tags

          

            You can set a fixed css class for your tags, or determine dynamically by provinding a custom function.
          

          

            
          

          

            

              

                
                  Show code
                
              

              

                

                  
<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>

                

              

            

          

          
statementreturns
$("input").val()
$("input").tagsinput('items')

        


        

          
AngularJS support

          

            Include bootstrap-tagsinput-angular.js and register the 'bootstrap-tagsinput' in your Angular JS application to use the bootstrap-tagsinput directive.
          

          

            
            
          

          

            

              

                
                  Show code
                
              

              

                

                  
<bootstrap-tagsinput
  ng-model="cities"
  typeahead-source="queryCities"
  tagclass="getTagClass"
  itemvalue="value"
  itemtext="text">
</bootstrap-tagsinput>

<script>
angular.module('AngularExample', ['bootstrap-tagsinput'])
  .controller('CityTagsInputController',
    function CityTagsInputController($scope) {
      // Init with some cities
      $scope.cities = [
        { "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"    }
      ];

      $scope.queryCities = function(query) {
        return $http.get('cities.json');
      };

      $scope.getTagClass = function(city) {
        switch (city.continent) {
          case 'Europe'   : return 'badge badge-info';
          case 'America'  : return 'label label-important';
          case 'Australia': return 'badge badge-success';
          case 'Africa'   : return 'label label-inverse';
          case 'Asia'     : return 'badge badge-warning';
        }
      };
    }
  );
</script>

                

              

            

          

          

            
              
statementreturns

            
            
              
$scope.cities
{{cities}}

              
$("select").val()

              
$("select").tagsinput('items')

            
          

        

      


      

        

          
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, 188], which are ENTER and comma)

                
$('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. (default: undefined)

                
$('input').tagsinput({
  maxTags: 3
});

              		
            

            

              maxChars
              
                
Defines the maximum length of a single tag. (default: undefined)

                
$('input').tagsinput({
  maxChars: 8
});

              		
            

            

              trimValue
              
                
When true, automatically removes all whitespace around tags. (default: false)

                
$('input').tagsinput({
  trimValue: true
});

              		
            
 
            

              allowDuplicates
              
                
When true, the same tag can be added multiple times. (default: false)

                
$('input').tagsinput({
  allowDuplicates: true
});

              		
            
             
            

              maxChars
              
                
Defines the maximum length of a single tag.

                
$('input').tagsinput({
  maxChars: 8
});

              		
            

            

              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();
  }
});

              		
            

          
        

      


      

        

          
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');

              		
            

          
        

      


      

        

          
Events

        

        

          
            

              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
});