Changelog from 1.0

Support for selection of multiple values. See multiple option in the docs.
Built-in tagging support. See the Tagging example.
Ability to reset back to placeholder once a selection has been made. See allowClear option in the docs.
Simplified paging of remote datasets by tracking the page number automatically.
Minimum required jQuery version changed from 1.7+ to 1.4.2

Examples

The Basics

Select2 can take a regular select box like this:

and turns it into:

with support for quick option filtering via a search box

Example Code

<head>
    <link href="select2.css" rel="stylesheet"/>
    <script src="select2.js"></script>
    <script>
        $(document).ready(function() { $("#e1").select2(); });
    </script>
</head>
<body>
    <select id="e1">
        <option value="AL">Alabama</option>
        ...
        <option value="WY">Wyoming</option>
    </select>
</body>

Multi-Value Select Boxes

Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute. Select2 automatially picks up on this:

Example Code

Placeholders

A placeholder value can be defined and will be displayed until a selection is made:

The placeholder can be declared via a data-placeholder attribute attached to the select, or via the placeholder configuration element as seen in the example code

Optionally, a clear button (visible once a selection is made) is available to reset the select box back to the placeholder value.

Example Code

Minimum Input

Select2 supports a minimum input setting which is useful for large remote datasets where short search terms are not very useful:

Example Code

Templating

Various display options of the Select2 component can be changed:

Example Code

Loading Data

Select2 uses a function to load result data. Here is a trivial example that creates choices that consist of user's input repeated a number of times:

In order to take advantage of custom data loading Select2 should be attached to an input type='hidden' tag, otherwise data is parsed from select's option tags.

Example Code

Loading Array Data

Select2 provides some shortcuts that make it easy to access local data stored in an array instead of having to write a query function mentioned in the example above.

Example below inlines the data by specifying an array in the data element. Items in such an array must have id and text keys.

If your data does not have a text key, an alternative key can be specified as a string:

or as a function:

Example Code

Loading Remote Data

Select2 comes with AJAX/JSONP support built in. In this example we will search for a movie using Rotten Tomatoes API:

If this example does not work it is probably because the Rotten Tomatoes API key usage of 10000 requests per day has been exhausted. Please try again tomorrow.

Example Code

Select2 uses jQuery's $.ajax function to execute the remote call by default. An alternative transport function can be specified in the ajax settings, or an entirely custom implementation can be built by providing a custom query function instead of using the ajax helper

Infinite Scroll with Remote Data

Select2 supports lazy-appending of results when the result list is scrolled to the end. In order to enable the remote service must support some sort of a paging mechanism and the query function given to Select2 must take advantage of it. The following example demonstrates how this can be set up. Search for some keyword and then scroll the result list to the end to see more results load:

If this example does not work it is probably because the Rotten Tomatoes API key usage of 10000 requests per day has been exhausted. Please try again tomorrow.

Example Code

Programmatic Access

Select2 supports methods that allow programmatic control of the componentL

Example Code

Change Event

Select2 triggers the change event on the original element whenever its value is changed by the user

Example Code

Tagging Support

Select2 can be used to quickly set up fields used for tagging

Note that when tagging is enabled the user can select from pre-existing tags or create a new tag by picking the first choice which is what the user has typed into the search box so far.

Example Code

Reacting to external value changes

Select2 can react to external value changes and keep its selection in-sync. This feature allows Select2 to work seamlessly with front-end frameworks that use data binding between ui components and model values.

This feature is only available when initSelection() function is provided in the options. This function is needed to map the choice ids set on the element to objects used by Select2. This function is set by default when Select2 is attached to a select or when the tags helper function is used.

Example Code

Select2 Lifecycle

Example Code

Parameter

Type

Description

object

A choice object

string

the id of the object

Parameter

Type

Description

object

The selected result object returned from the query function

string

Html that represents the selection

Parameter

Type

Description

object

One of the result objects returned from the query function

string

Html that represents the result

Parameter

Type

Description

term

string

Search string entered by user

string

Message html

Parameter

Type

Description

term

string

Search string entered by user

minLength

int

Minimum required term length

string

Message html

Parameter

Type

Description

term

string

Search string entered by user

object (optional)

Object representing the new choice. Must at least contain an id attribute.

Parameter

Type

Description

element

jQuery array

element Select2 is attached to

object or array of objects

Object representing the choice to be selected, or an array of such objects in case Select2 is in multi mode.

$("#tags").select2({ initSelection : function (element) { var data = []; $(element.val().split(",")).each(function () { data.push({id: this, text: this}); }); return data; } });

Parameter

Type

Description

result.results

[object]

Array of result objects. The default renderers expect objects with id and text keys. The id attribute is required, even if custom renderers are used.

result.more

boolean

trueif more results are available for the current search term

Parameter

Type

Description

term

string

Search term

page

int

1-based page number tracked by Select2 for use with infinite scrolling of results

object

Object containing url paramters

Parameter

Type

Description

data

object

Retrieved data

page

int

Page number that was passed into the data function above

object

Results object. See "options.callback" in the "query" function for format.

Single-Valued

Multi-Valued

Attached to select

Value of the value attribute of the option that should be selected

Array of values specified to the left. null for empty.

Attached to input[type=hidden]

An object representing the selection. Should at least contain an id key. The rest of the keys should be determined by the custom rendering function, the default rendering function only needs an additional text key

Array of objects specified to the left. null for empty.

Changelog from 1.0

Examples

The Basics

Example Code

Multi-Value Select Boxes

Example Code

Placeholders

Example Code

Minimum Input

Example Code

Templating

Example Code

Loading Data

Example Code

Loading Array Data

Example Code

Loading Remote Data

Example Code

Infinite Scroll with Remote Data

Example Code

Programmatic Access

Example Code

Change Event

Example Code

Tagging Support

Example Code

Reacting to external value changes

Example Code

Select2 Lifecycle

Example Code

Documentation

Constructor

val

destroy

open

close

Events

change