jQuery TokenInput

This is a mod based on the popular tokeninput jquery plugin written by James Smith (loopj). It 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.

See a demontration
Download latest master branch


  1. My Customizations
  2. Loopj Features
  3. How to Use
    1. Configuration – Search Settings
    2. Pre-Population
    3. Display Settings
    4. Tokenization Settings
    5. Events / Callbacks
    6. Methods
  4. Reporting Bugs or Feature Requests
  5. License

My Customizations

  • ThemeRoller support
  • Show the list without typing (minChars = 0)(demo)
  • Extra parameters with function support, so you can get whatever value you want
  • Make json post requests (instead of x-www-form-urlencoded) to be compatible with ASP.NET WebForms WebMethod’s

Loopj 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

How to use

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 or POST 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":"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":"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.7.2/jquery.min.js"></script>
<link rel="stylesheet" href="content/theme/jquery-ui-custom.css" type="text/css" media="all">

<script type=”text/javascript” src=”yourfiles/jquery.tokeninput.js”></script>
<link rel=”stylesheet” type=”text/css” href=”yourfiles/jquery.tokeninput.css” />

<script type=”text/javascript”>
$(document).ready(function () {


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

The HTTP method (eg. GET, POST) to use for the server request. default: “GET”.

The name of the query param which you expect to contain the search term on the server-side. default: “q”.

The type of request to post to server when using http post. default: “application/x-www-form-urlencoded”

The mime type that your server will use. default: “application/json”

The delay, in milliseconds, between the user finishing typing and the search being performed. default: 300 (demo).

The minimum number of characters the user must enter before a search is performed.default: 1 (demo).

The javascript/json object attribute to search. default: “name” (demo).

The name of the json object in the response which contains the search results. This is typically used when your endpoint returns other data in addition to your search results. Use null to use the top level response object. default: null.

Force JSONP cross-domain communication to the server instead of a normal ajax request. Note: JSONP is automatically enabled if we detect the search request is a cross-domain request. default: false.

Pre-population Settings

Prepopulate the tokeninput with existing data. Set to an array of JSON objects, eg:[{id: 3, name: "test"}, {id: 5, name: "awesome"}] to pre-fill the input. default: null(demo).

Display Settings

The text to show in the dropdown label which appears when you first click in the search field. default: “Type to search” (demo).

The text to show in the dropdown label when no results are found which match the current query. default: “Nothing found” (demo).

The text to show in the dropdown label when a search is currently in progress. default: “Searching…” (demo).

The text to show on each token which deletes the token when clicked. If you wish to hide the delete link, provide an empty string here. Alternatively you can provide a html string here if you would like to show an image for deleting tokens. default: ×(demo).

Set this to false to disable animation of the dropdown default: true (demo).

Set this to a string, when including theme -roller custom prefix css files to set the css class prefix.

The maximum number of results shown in the drop down. Use null to show all the matching results. default: null

A function that returns an interpolated HTML string for each result. Use this function with a templating system of your choice, such as jresig microtemplates or mustache.js. Use this when you want to include images or multiline formatted results default: function(item){ return “<li><a>” + item.propertyToSearch + “</a></li>” } (demo).

A function that returns an interpolated HTML string for each token. Use this function with a templating system of your choice, such as jresig microtemplates or mustache.js. Use this when you want to include images or multiline formatted tokens. Quora’s people invite token field that returns avatar tokens is a good example of what can be done this option. default: function(item){ return “<li>” + item.propertyToSearch + “</li>” } (demo).

Tokenization Settings

The maximum number of results allowed to be selected by the user. Use null to allow unlimited selections. default: null (demo).

The separator to use when sending the results back to the server. default: “,”.

Prevent user from selecting duplicate values by setting this to truedefault: false (demo).

The value of the token input when the input is submitted. Set it to id in order to get a concatenation of token IDs, or to name in order to get a concatenation of names. default: id

Events / Callbacks

A function to call whenever we receive results back from the server. You can use this function to pre-process results from the server before they are displayed to the user.default: null (demo).

A function to call whenever the user adds another token to their selections. defaut: null(demo).

A function to call whenever the user removes a token from their selections. default: null(demo).

A function to call after initialization is done and the tokeninput is ready to use. default: null


selector.tokenInput("add", {id: x, name: y});
Add a new token to the tokeninput with id x and name y.

selector.tokenInput("remove", {id: x});
Remove the tokens with id x from the tokeninput.

selector.tokenInput("remove", {name: y});
Remove the tokens with name y from the tokeninput.selector.tokenInput("clear");Clear all tokens from the tokeninput.

Gets the array of selected tokens from the tokeninput (each item being an object of the kind {id: x, name: y}).

Reporting Bugs or Feature Requests

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



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.


4 pensamentos sobre “jQuery TokenInput

  1. My name’s Alisha from Amsterdam, Netherlands and I have to say your article is really informative. The quality of your post is very nice and I can trust you are an expert on this subject. With your permission, would you let me to grab your RSS feed to keep updated with future content? Thanks a million and please carry on the good work.

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair /  Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair /  Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair /  Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair /  Alterar )


Conectando a %s