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 automatically 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.

When placeholder is used for a non-multi-value select box, it requires that you include an empty <option></option> tag as your first option.

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

You can set data- attributes to <option> (or <optgroup>) and use them inside templating functions:

<select>
    <option value="0" data-foo="bar">option one</option>
    ...
</select>

function format(state) {
    var originalOption = state.element;

    return "<img class='flag' src='images/flags/" + state.id.toLowerCase() + ".png' alt='" + $(originalOption).data('foo') + "' />" + state.text;
}

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

Maximum Selection Size

Select2 allows the developer to limit the number of items that can be selected in a multi-select control. In the example below only 3 or less items can be selected.

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:

data can also itself be a function that returns a results object:

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.

Select2 requires an id property to be set for items returned in the results parameter. If your result doesn't have an 'id' property then you can specify it in the id parameter of select2. For example: id: function(object) { return object.text; } will use the text property as the id.

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 component:

Example Code

Events

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

open event is triggered on the original element whenever the dropdown needs to be opened:

Event Log

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

Maximum Input Length

Select2 can be set a limit on the number of characters that can be entered per tag.

You would not be able to enter any input of more than 10 characters long.

Example Code

Auto Tokenization

Select2 supports ability to add choices automatically as the user is typing into the search field. This is especially convenient in the tagging usecase where the user can quickly enter a number of tags by separating them with a comma or a space. Try typing in the search field below and entering a space or a comma.

Note that the separators are defined in the tokenSeparators option.

Note that this example uses the built in tokenizer function, but a custom one can be provided in the options.

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

Select2 Drag and Drop Sorting

Select2 supports drag and drop sorting of selected choices. Select2 does not, itself, provide the necessary code to perform dragging and dropping, instead it provides hooks that other libraries can use to provide the behavior. In this example we are using JQuery UI's sortable() plugin.

The sorting is only available when Select2 is attached to a hidden input field.

Example Code

Select2 Disabled Mode

Example Code

Custom Matcher

Unlike other dropdowns on this page, this one matches options only if the term appears in the beginning of the string as opposed to anywhere:

The dropdown below matches on custom attributes of the option tag. For example, the `blue` option can be matched by entering either `blue` or `cyan`:

Example Code

Sorting Displayed Results

Unlike other dropdowns on this page, this one filters results by query string normally, but returns the matched results sorted from shortest to longest by string length. Try typing 'e' and seeing how the results are sorted. This function is useful for sorting results by relevance to a user's query.

Example Code

Responsive Design - Percent Width

Select2's width can be set to a percentage of its parent to support responsive design. The two Select2 boxes below are styled to 50% and 75% width respectively.

Select2 will do its best to resolve the percent width specified via a css class, but it is not always possible. The best way to ensure that Select2 is using a percent based width is to inline the style declaration into the tag.

Example Code

Disabled options

In case that you need to disable certain options so that they can't be selected by the select2 interface, you can now pass in disabled: true with your data. Please note: This also works for incoming values from ajax. When attached to a <select> element, Select2 will respect its <option> elements' disabled property.

Example Code

Lock selections

In the event that you need to lock certain selections so that they can't be removed by the select2 interface, you can now pass in locked: true with your data. Please note: This also works for incoming values from ajax.

Example Code

Diacritics Support

Select2's default matcher will ignore diacritics, making it easier for users to filter results in international selects. Type "aero" into the select below:

Changelog (Loading...)

Browser Compatibility

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

Maximum Selection Size

Example Code

Loading Array Data

Example Code

Loading Remote Data

Example Code

Infinite Scroll with Remote Data

Example Code

Programmatic Access

Example Code

Events

Event Log

Example Code

Tagging Support

Example Code

Maximum Input Length

Example Code

Auto Tokenization

Example Code

Reacting to external value changes

Example Code

Select2 Lifecycle

Example Code

Select2 Drag and Drop Sorting

Example Code

Select2 Disabled Mode

Example Code

Custom Matcher

Example Code

Sorting Displayed Results

Example Code

Responsive Design - Percent Width

Example Code

Disabled options

Example Code

Lock selections

Example Code

Diacritics Support

Documentation

Constructor

Example Data

Example Hierarchical Data

val

data

destroy

open

close

enable(boolean)

readonly(boolean)

container

onSortStart

onSortEnd

Events

change

select2-opening

select2-open

select2-close

select2-highlight

select2-selecting

select2-clearing

select2-removing

select2-removed

select2-loaded

select2-focus

select2-blur