README.md

jQuery Tagz Plugin

This plugin converts any standard HTML input field into a style-able tag list.

View Demo

This plugin is based on the jQuery Tag Input plugin by XOXCO. The original Github page can be viewed here.

Installation

Include script after the jQuery library (unless you are packaging scripts somehow else):

<script type="text/javascript" src="/path/to/jquery.tagz.js"></script>

Create a HTML input field in your form.

<input type="text" id="tags" />

Initialise the plugin

$('#tags').tagz();

Options

autocompleteOnly

Restricts input field to only accept values generated by jQuery Autocomplete. Requires jQuery Autocomplete to be enabled.

Default value: false

autocompleteOptions

Option values to be passed to jQuery Autocomplete. Please refer to this for valid option values.

Default value: undefined

autosize

Default value: true

comfortZone

Default value: 20

delimiter

Symbol used as separator.

Default value: ','

height

Tag list container height.

Default value: 100

inputPadding

Default value: 12

minChars

Minimum number of characters for tag.

Default value: 0

placeholderColor

Colour of placeholder text.

Default value: '#666'

placeholderText

Text to be displayed in container.

Default value: 'Add a tag'

readonly

Disables input. Useful for displaying input tag list.

This value is overridden if the HTML input field has the disabled attribute.

Default value: false

removeWithBackspace

Allows tag remove using backspace. Set to false to disable.

Default value: true

showInput

Shows the original HTML input field.

Default value: false

unique

If set to true, no duplicates are allowed.

Default value: true

width

Tag list container width.

Default value: 300

Methods

addTag

$(selector).tagz('addTag', 'New Tag');

Append a new tag to the tag list.

Returns matching DOM element if single, array of matching DOM elements if multiple.

removeTag

$(selector).tagz('removeTag', 'New Tag');

Removes an existing tag from the tag list.

Returns matching DOM element if single, array of matching DOM elements if multiple.

destroy

$(selector).tagz('destroy');

Destroys the instance and restores the elements back to pre-init state.

Returns matching DOM element if single, array of matching DOM elements if multiple.

tagExist

$(selector).tagz('tagExist', 'Tag to check');

Checks if tag exists in tag list. Only works when used with single DOM element. Multiple DOM elements will return an array of matching DOM elements.

Returns boolean true if tag exists, and false if not.

Events

onReady

Fires when instance is ready.

$(selector).tagz({
    onReady: function(){
        // do something
    }
})

onDestroy

Fires when instance is destroyed.

$(selector).tagz({
    onDestroy: function(){
        // do something
    }
})

onAddTag

Fires when a tag is added.

$(selector).tagz({
    onAddTag: function(addedTagValue){
        // do something
    }
})

onRemoveTag

Fires when a tag is removed.

$(selector).tagz({
    onRemoveTag: function(removedTagValue){
        // do something
    }
})

onChange

Fires when tag list is changed.

$(selector).tagz({
    onChange: function(newTagList){
        // do something
    }
})