Select2

Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results. Look and feel of Select2 is based on the excellent Chosen library.

Learn more on GitHub» Download»

Examples

The Basics

Select2 takes a select box like this:

and turns it into:

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>

Placeholders

A placeholder text can be defined that will be displayed until a selection is made:

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 echoed a number of times:

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:

Example Code

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:

Example Code

Pragmatic Access

Select2 supports methods that allow pragmatic control of the componentL

Example Code

Documentation

Constructor

Parameter Type Description

minimumInputLength int Number of characters necessary to start a search

placeholder object Initial value that is selected if no other selection is made

formatSelection

function

Function used render the current selection.

formatSelection(object)

Parameter	Type	Description
object	object	The selected result object returned from the `query` function
<returns>	string	Html that represents the selection

The default implementation expects the object to have a text property that is returned.

formatResult

function

Function used to render a result that the user can select.

formatResult(object)

Parameter	Type	Description
object	object	One of the result objects returned from the `query` function
<returns>	string	Html that represents the result

The default implementation expects the object to have a text property that is returned.

formatNoMatches

function

Function used to render the "No matches" message

formatNoMatches(term)

Parameter	Type	Description
term	string	Search string entered by user
<returns>	string	Message html

formatInputTooShort

function

Function used to render the "Search input too short" message

formatInputTooShort(term, minLength)

Parameter	Type	Description
term	string	Search string entered by user
minLength	int	Minimum required term length
<returns>	string	Message html

query

function/string

Function used to query results for the search term.

query(options)

Parameter Type Description

options.term string Search string entered by user

options.vars object Object from the previous result, see options.callback

options.callback

function

Callback function that should be called with the result object. The results object:

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.vars	object	A user-defined object that will be passed into the next invocation of `query` if more results need to be loaded
result.more	boolean	`true`if more results are available for the current search term

"ajax" - use the built in ajax query function. This function will handle throttling and dropping out-of-order responses.

ajax

object

Options for the built in ajax query function.

Parameter Type Description

url string Ajax url

dataType stringt Data type for the request. ajax, jsonp, other formats supported by jquery

quietMillis int Number of milliseconds to wait for the user to stop typing before issuing the ajax request

data

function

Function to generate query parameters for the ajax request.

data(term, vars)

Parameter	Type	Description
term	string	Search term
vars	object	The vars object from the previous search's result
<returns>	object	Object containing url paramters

results

function

Function used to build the query results object from the ajax response

results(term, vars)

Parameter	Type	Description
term	string	Search term
vars	object	The vars object from the previous search's result
<returns>	object	Results object. See "options.callback" in the "query" function for format.

val

Gets or sets the selection. If the value parameter is not specified, the id attribute of the currently selected element is returned. If the value parameter is specified it will become the current selection.

Parameter	Type	Description
value (optional)	object	Result object for the new selection, or the `id` attribute of a loaded result object

Example:

alert("Selected value is: "+$("#e8").select2("val")); $("#e8").select2("val", {id:"CA", text:"Califoria"});

Events

opened

Signalled when the search dropdown has been opened

closed

Signalled when the search dropdown has been closed

cancelled

Signalled when the user cancells the selection of a result. For example, when ESC is pressed after the dropdown has been opened

selected

Signals a selection has been made

Select2

Examples

The Basics

Example Code

Placeholders

Example Code

Minimum Input

Example Code

Templating

Example Code

Loading Data

Example Code

Loading Remote Data

Example Code

Infinite Scroll with Remote Data

Example Code

Pragmatic Access

Example Code

Documentation

Constructor

val

Events

opened

closed

cancelled

selected

Community