Taggle.js

Form-ready, Delicious style tagging made easy.

Example 1 - Creating a basic Taggle

This example is as simple as it gets. Duplicate tags are prevented by default. You can also delete tags by pressing backspace or hovering and clicking with your mouse.

HTML:
<div id="example1"></div>
JavaScript:
new Taggle('example1');
Example 2 - Prefilled tags

It’s easy to prepopulate the text field as well. Just pass an array of tags as displayed below.

HTML:
<div id="example2"></div>
JavaScript:
new Taggle('example2', {
    tags: ['These', 'are', 'prefilled', 'tags']
});

Example 3 - Duplicate tag alert

This example takes advantage of how much CSS control Taggle.js allows you to have. Specify your own duplicate CSS class by using the duplicateTagClass option. Try entering one of the already existing tags to see a subtle alert notifying you of the tag.

Note: the bounce animation happens as a result of the css class being added. Not javascript. Therefore you will not see the animation in IE9 and below.

HTML:
<div id="example3"></div>
JavaScript:
new Taggle('example3', {
    tags: ['Try', 'entering', 'one', 'of', 'these', 'tags'],
    duplicateTagClass: 'bounce'
});

Example 4 - Autocomplete

Taggle.js just provides the basic functionality to add tags to a field but it also provides a basic API so you can wrap it for additional functionality with other libraries such as jQueryUI Autocomplete. Same HTML. Just a little bit more javascript code.

HTML:
<div id="example4"></div>
JavaScript:
var example4 = new Taggle('example4');
var container = example4.getContainer();
var input = example4.getInput();

$(input).autocomplete({
    source: arrayOfValues, // See jQuery UI documentaton for options
    appendTo: container,
    position: { at: "left bottom", of: container },
    select: function(event, data) {
        event.preventDefault();
        //Add the tag if user clicks
        if (event.which === 1) {
            example4.add(data.item.value);
        }
    }
});

Example 5 - onBeforeTagAdd/onTagAdd & onBeforeTagRemove/onTagRemove

Want to hook into before a tag is added or removed? Okay. Want to call a callback function after a tag has been added or removed? Fine.

I’m using innerHTML for simplicity however you should look into innerText or textContent depending on what browser you’re supporting.

HTML:
<div id="example5"></div>
<p id="example5-event"></p>
JavaScript:
var text = document.getElementById('example5-event');

// Make sure to return true or false in onBeforeTagAdd and onBeforeTagRemove
new Taggle('example5', {
    onBeforeTagAdd: function(event, tag) {
        return confirm('You really wanna add ' + tag + '?');
    },
    onTagAdd: function(event, tag) {
        text.innerHTML = 'You just added ' + tag;
    },
    onBeforeTagRemove: function(event, tag) {
        return confirm('You really wanna remove ' + tag + '?');
    },
    onTagRemove: function(event, tag) {
        text.innerHTML = 'You just removed ' + tag;
    }
});

Example 6 - add / remove

You can programatically add and remove tags as well.

HTML:
<div id="example6"></div>
JavaScript:
var taggle = new Taggle('example6');

taggle.add('one');
taggle.add(['two', 'three', 'four', 'four', 'five', 'five']);
taggle.remove('five');
taggle.remove('four', true);

Example 7a - Allowed tags

Sometimes you’ll want to restrict the users to adding only certain tags.

HTML:
<div id="example7a"></div>
JavaScript:
var taggle = new Taggle('example7a', {
    placeholder: 'Type your favorite type of juice... (hint: orange)',
    allowDuplicates: true,
    allowedTags: ['orange']
});

Example 7b - Disallowed tags

Conversely, you’ll want to restrict the users from adding certain tags.

HTML:
<div id="example7b"></div>
JavaScript:
var taggle = new Taggle('example7b', {
    placeholder: 'Type your favorite type of juice... (hint: apple)',
    allowDuplicates: true,
    disallowedTags: ['apple']
});

Misc - Tags around the web

Tag fields can be really useful because it makes it easy for your users to provide the type of data values you need without having to worry about if they submitted values with trailing spaces, extra commas, etc.

As you can see below, it’s easy to style Taggle.js with just a little bit of css.

Delicious
Stack Overflow

Options

additionalTagClasses: [String='']

By default a class of taggle will be assigned to each tag. If you need more, add them in one string separated by spaces.

allowDuplicates: [Boolean=false]

Set to true if you want to allow duplicate tags to be entered in the taggle field.

preserveCase: [Boolean=false]

Set to true if you want to allow tags to retain case as entered in the taggle field (lowercased by default).

saveOnBlur: [Boolean=false]

Allow the saving of a tag on blur, rather than it being removed by default.

clearOnBlur: [Boolean=true]

Clear the input element on blur if there is a text value.

duplicateTagClass: [String='']

The class name that will be set onto duplicate tag.

containerFocusClass: [String='active']

This will be the class added to the taggle field div when focused.

focusInputOnContainerClick: [Boolean=true]

If true then input will be focused when container receives a click event.

hiddenInputName: [String='taggles[]']

Since a hidden input is appended for each tag added, you might need a name for them when submitting to the server.

placeholder: [String='Enter tags...']

A placeholder.

submitKeys: [188, 9, 13]

Keycodes that will add a tag. Comma, Tab, and Enter are the recommended and default keyCodes.

tabIndex: [Number=1]

If your taggle field is within a form, it might be useful to specify a tabIndex so that a user can still tab through form fields like normal.

tags: [Array=[]]

These will be the tags that should be preloaded in the taggle field when the plugin loads.

delimeter: [',']

The default delimeter character to split tags on.

attachTagId: [Boolean=false]

Add an ID to each of the tags that will be available in onTagAdd, onBeforeTagRemove, & onTagRemove.

allowedTags: [Array=[]]

Tags that the user will be restricted to.

inputFormatter(inputElement)

Function hook called with the to-be-added input DOM element.

tagFormatter(element)

Hook fired before the tag li element is appended to the DOM. This gives the author a chance to edit the list item before it is added. Must return an li element.

onBeforeTagAdd(event, tag)

Hook fired before a tag is added. Provides the event and tag text. Return false to prevent the tag from being added.

onBeforeTagRemove(event, tag [, callback])

Hook fired before a tag is removed. Provides the event and tag text. Return a falsy value to prevent the tag from being removed. The callback argument can be called to remove the tag.

onTagAdd(event, tag)

Callback fired whenever a tag is added. Provides the event and tag text.

onTagRemove(event, tag)

Callback fired whenever a tag is removed. Provides the event and tag text.

Methods

setOptions(options)

Set options at runtime. This should be an object with the taggle options as keys

add(tag(s))

Pass an array of strings or just one string to programatically add tags.

remove(tag, remove_all=false)

Pass a string to remove the most recent occurance of the tag. Pass true to the second argument to remove all occurances of the tag.

removeAll()

Remove all tags at once, including duplicates.

getTags(): Object

Get an object with an array of the tag text and an array of tag list elements.

getTagElements(): Array

Get an object with an array of the tag list elements.

getTagValues(): Array

Get an array of the tag text.

getInput(): HTMLElement

Get the actual text input.

getContainer(): HTMLElement

Get the original textarea container.

disable()

Disable all button and input elements within the component via the disabled attribute.

enable()

Enable all button and input elements within the component by removing the disabled attribute.

setData(Any)

Sets arbitrary data on the instance.

getData(): Object

Gets the arbitrary data on the instance.

removeEvents()

Disable all events for the taggle instance. Applies to all default elements created by the library.

attachEvents()

Re attach instance events.