jQuery Tokeninput: A Tokenizing Autocomplete Text Entry

Overview

Tokeninput is a jQuery plugin which allows your users to select multiple items from a predefined list, using autocompletion as they type to find each item. You may have seen a similar type of text entry when filling in the recipients field sending messages on facebook.

Features

• Intuitive UI for selecting multiple items from a large list
• Easy to skin/style purely in css, no images required
• Supports any backend which can generate JSON, including PHP, Rails, Django, ASP.net
• Smooth animations when results load
• Select, delete and navigate items using the mouse or keyboard
• Client-side result caching to reduce server load
• Crossdomain support via JSONP
• Callbacks when items are added or removed from the list
• Preprocess results from the server with the onResult callback
• Programatically add, remove, clear and get tokens
• Customize the output format of the results and tokens

Screenshots

Vertical list style item selection

Facebook style item selection

Installation & Setup

Create a server-side script to handle search requests

Create a server-side script (PHP, Rails, ASP.net, etc) to generate your search results. The script can fetch data from wherever you like, for example a database or a hardcoded list. Your script must accept a GET parameter named q which will contain the term to search for. E.g. http://www.example.com/myscript?q=query

Your script should output JSON search results in the following format:

[
    {"id":"856","name":"House"},
    {"id":"1035","name":"Desperate Housewives"},
    ...
]

You may optionally specify an attribute of "readonly" and set it to true if you would like some of the tokens to be non-removable:

[
    {"id":"856","name":"House","readonly":true},
    {"id":"1035","name":"Desperate Housewives"},
    ...
]

Note that you may omit "readonly" on entities where it is not necessary. This attribute is acceptable wherever JSON entities are passed, e.g. .tokenInput("add") (see Methods section below).

Include and initialize the plugin

Include jQuery and Tokeninput Javascript and stylesheet files on your page, and attach to your text input: Tokeninput stylesheet:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script type="text/javascript" src="yourfiles/jquery.tokeninput.js"></script>
<link rel="stylesheet" type="text/css" href="yourfiles/token-input.css" />

<script type="text/javascript">
$(document).ready(function () {
    $("#my-text-input").tokenInput("/url/to/your/script/");
});
</script>

Configuration

The tokeninput takes an optional second parameter on intitialization which allows you to customize the appearance and behaviour of the script, as well as add your own callbacks to intercept certain events. The following options are available:

Search Settings

Pre-population Settings

Display Settings

Tokenization Settings

Callbacks

Methods

Reporting Bugs or Feature Requests

Please report any bugs or feature requests on the github issues page for this project here:

https://github.com/loopj/jquery-tokeninput/issues

License

Tokeninput is released under a dual license. You can choose either the GPL or MIT license depending on the project you are using it in and how you wish to use it.