jquery.taginput Examples and API

Examples

Basic usage

To create an taginput widget simply call: 

$('selector').taginput();

The element on which you create a taginput widget should be an input element.

If you want to overwrite default options simply pass an object literal to the constructor: 

$('selector').taginput( { option: value } );

To call methods related to the widget we use the jQuery UI widget style: 

$('selector').taginput('add', 'someTag');

Apply different ui-styles

You can apply different ui-styles on the widget using the style option. 

$('selector').taginput({
	style: 'jqueryui'
});

$('selector').taginput({
	style: 'bootstrap'
});

$('selector').taginput({
    style: {
      	tagTpl: $('#wrapperTpl').html(),
       	wrapperTpl: '<div class="custom-style">',
        deleteHandler: '.ui-icon-close'
    }
});

Options

style

Description

Determines the ui style the widget is created with, which is either a preset (pass a String) or a custom style (pass an Object).

When passing an object, the following properties must be set:

tagTpl
HTML template representing a tag. Use {{label}} as placeholder for the label.
wrapperTpl
HTML template representing the wrapper around the input field.
deleteHandler
jQuery selector for the element on which a click-handler is attached which will delete the tag.

type
String ('jqueryui' or 'bootstrap') or Object
default
'jqueryui'

separateKeyCodes

Description

Determines on which key codes a tag should be created.

type
Number array
default
[32, 13, 9] (whitespace, enter, tab)

placeholder

Description

The value of the placeholder of the newly created input field.

type
String
default
'Add tag...'

allowMultiple

Description

Determines whether multiple tags with the same value are allowed.

type
Boolean
default
false

caseSensitive

Description

Determines whether to treat tag values case-sensitive or not. In other words: Is the value 'Test' unequal 'test'?

type
Boolean
default
false

Callbacks

onExists( $tag )

Description

Called when a tag value is added that already exists.

parameters
$tag, jQuery object reffering to the already existing tag element
default
function($tag) {
      $tag.hide().fadeIn();
}

onAdd( value )

Description

Called when a tag is added.
Return false to avoid adding the tag.

parameters
value, value of the tag
returns
Boolean, whether to add the tag or not

onRemove( value )

Description

Called when a tag is removed.
Return false to avoid removing the tag.

parameters
value, value of the tag
returns
Boolean, whether to remove the tag or not

Methods

add( tag )

Description

Adds the given tag.

tag
String representing a tag value.

remove( tag )

Description

Removes the given tag if it exists.

tag
String representing a tag value.

get( )

Description

Returns an array of the present tags values.

returns
Array of tag values.

set( tags )

Description

Clears all present tags and adds the given ones.

tags
Array of tag values

clear( )

Description

Clears all present tags.

focus( )

Description

Focuses the input field.

getInputElement( )

Description

Returns the input field created for the widget.

returns
jQuery object