--- layout: main title: Select2 1.0 group: navigation version: 1.0 ---

## 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

### Programmatic Access

Select2 supports methods that allow programmatic 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 parameters

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:"California"});

## Events

### opened

Signalled when the search dropdown has been opened

### closed

Signalled when the search dropdown has been closed

### cancelled

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

### selected

Signals a selection has been made