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

Changelog from 2.0

  • Added support for disabled mode. See Disabled Mode example
  • Added ability to provide custom matcher functions. See Custom Matcher Function example
  • Minimum required jQuery version bumped to 1.4.4

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

Browser Compatibility

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

        

    






    

        
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 component

        

            
            
            
            
        

        

            

        

        

            
            
            
            
        

        

            

        

    

    

        
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

           
           

    






    
    

        
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

        


    

    

        
Example Code

           
           

    



















    
Documentation






    
Constructor







    ParameterTypeDescription



minimumInputLengthintNumber of characters necessary to start a search


minimumResultsForSearchint
    

        The minimum number of results that must be initially (after opening the dropdown for the first time)
        populated in order to keep the search field. This
        is useful for cases where local data is used with just a few results, in which case the search box
        is not very useful and wastes screen space.
    

    
Only applies to single-value select boxes





placeholderobject/string
    
Initial value that is selected if no other selection is made.

    

        The value can be specified either as an object or as a string. If
        specified as a string any custom formatSelection function will be
        bypassed and the string value will be rendered directly.
    

    
The placeholder can also be specified as a data-placeholder attribute on the select
        or input element that Select2 is attached to. In this case only string
        values are supported
    


    
Note that because browsers assume the first option element
        is selected in
        non-multi-value select boxes an empty first option element must be provided (<option></option>)
        for the placeholder to work.
    


    
When Select2 is used in multi-select mode the placeholder must be a string.





    allowClear
    boolean
    
        

            Whether or not a clear button is displayed when the select box has a selection. The
            button,
            when clicked, resets the value of the select box back to the placeholder, thus this option is
            only
            available when the placeholder is specified.
        

        
When attached to a select an option with an empty value must be provided.
            This is the option that will be selected when the button is pressed since a select box requires
            at least one selection option.

        

            Also, note that this option only works with
            non-multi-value based selects because multi-value selects always provide such a button for every
            selected option.
        

    		




    multiple
    boolean
    
        

            Whether or not Select2 allows selection of multiple values.
        

        
When Select2 is attached to a select element this value will be ignored and select's
            multiple attribute will be used instead.
        

    		




    closeOnSelect
    boolean
    
        

            If set to true the dropdown is not closed after a selection is made, allowing for rapid selection of multiple items. By default this option is disabled.
        


        

            Only applies when configured in multi-select mode.
        

    		



idfunction
    Function used to get the id from the choice object or a string representing the key under which the id is stored.
    
id(object)

    

        
ParameterTypeDescription

        
objectobjectA choice object

        
<returns>stringthe id of the object

    

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



matcherfunction
    Used to determine whether or not the search term matches an option when a built-in query function is used.
    The built in query function is used when Select2 is attached to a select, or the local or tags helpers are used.
    
matcher(term, text)

    

        
ParameterTypeDescription

        
termstringsearch term

        
textstringtext of the option being matched

        
<returns>booleantrue if search term matches the option text, or false otherwise

    

    The default implementation is case insensitive and matches anywhere in the term:
    function(term, text) { return text.toUpperCase().indexOf(term.toUpperCase())>0; }



formatSelectionfunction
    Function used to render the current selection.
    
formatSelection(object)

    

        
ParameterTypeDescription

        
objectobjectThe selected result object returned from the query function

        
<returns>stringHtml that represents the selection

    

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



formatResultfunction
    Function used to render a result that the user can select.
    
formatResult(object)

    

        
ParameterTypeDescription

        
objectobjectOne of the result objects returned from the query function

        
<returns>stringHtml that represents the result

    

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



formatNoMatchesfunction
    Function used to render the "No matches" message
    
formatNoMatches(term)

    

        
ParameterTypeDescription

        
termstringSearch string entered by user

        
<returns>stringMessage html

    




formatInputTooShortfunction
    Function used to render the "Search input too short" message
    
formatInputTooShort(term, minLength)

    

        
ParameterTypeDescription

        
termstringSearch string entered by user

        
minLengthintMinimum required term length

        
<returns>stringMessage html

    




createSearchChoicefunction
    Creates a new selectable choice from user's search term. Allows creation of choices not available via the query
    function. Useful when the user can create choices on the fly, eg for the 'tagging' usecase.
    
createSearchChoice(term)

    

        
ParameterTypeDescription

        
termstringSearch string entered by user

        
<returns>object (optional)Object representing the new choice.
            Must at least contain an id attribute.

    

    If the function returns undefined or null no choice will be created. If a new
    choice is created it is displayed first in the selection list so that user may select it by simply pressing
    enter.

    
When used in combination with input[type=hidden] tag care
        must be taken to sanitize the id attribute of the choice object, especially stripping
        , as it is used as a value separator




initSelectionfunction
    Called when Select2 is created to allow the user to initialize the selection based on the value of the
    element select2 is attached to.
    

        Essentially this is an id->object mapping function.
    

    
initSelection(element)

    

        
ParameterTypeDescription

        
elementjQuery arrayelement Select2 is attached to

        
<returns>object or array of objectsObject representing the choice
            to be selected, or an array of such objects in case Select2 is in multi mode.

    

    
This function will only be called when there is initial input to be processed.

    Here is an example implementation used for tags. Tags are the simplest form of data where the id is also
    the text:

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






    query
    function
    
        Function used to query results for the search term.
        
query(options)

        

            
ParameterTypeDescription

            
options.termstringSearch string entered by user

            
options.pageint1-based page number tracked by Select2 for use with infinite scrolling of results

            
options.contextobjectAn object that persists across the lifecycle of queries for the same search term (the query to retrieve the initial results, and subsequent queries to retrieve more result pages for the same search term). When this function is first called for a new search term this object will be null. The user may choose to set any object in the results.context field - this object will then be used as the context parameter for all calls to the query method that will load more search results for the initial search term. The object will be reset back to null when a new search term is queried. This feature is useful when a page number is not easily mapped against the server side paging mechanism. For example, some server side paging mechanism may return a "continuation token" that needs to be passed back to them in order to retrieve the next page of search results.

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

                        
ParameterTypeDescription

                        
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.morebooleantrueif more results are available for the current search term

                        
results.contextobjectA user-defined object that should be made available as the context parameter to the query function on subsequent queries to load more result pages for the same search term. See the description of options.context parameter.

                    

                

        

        
In order for this function to work Select2 should be attached to a input type='hidden' tag instead of a select.

    		



ajaxobject
    Options for the built in ajax query function. This object acts as a shortcut for having to manually write a function that performs ajax requests. The built-in function supports more advanced features such as throttling and dropping out-of-order responses.

    

        
ParameterTypeDescription

        
transportfunctionFunction that will be used to perform the ajax request. Must be parameter-compatible with $.ajax. Defaults to $.ajax if not specified.
            Allows the use of various ajax wrapper libraries such as: AjaxManager. 

        
urlstringAjax url

        
dataTypestringData type for the request. ajax, jsonp, other formats supported by jquery

        
quietMillisintNumber of milliseconds to wait for the user to stop typing before issuing the ajax request

        
datafunction
            Function to generate query parameters for the ajax request.
            
data(term, page)

            

                
ParameterTypeDescription

                
termstringSearch term

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

                
contextobjectSee options.context parameter to the query function above.

                
<returns>objectObject containing url parameters

            

        

        
resultsfunction
            Function used to build the query results object from the ajax response
            
results(data, page)

            

                
ParameterTypeDescription

                
dataobjectRetrieved data

                
pageintPage number that was passed into the data function above

                
contextobjectSee options.context parameter to the query function above.

                
<returns>objectResults object. See "options.callback" in the "query" function for format.

            

        

    

    
In order for this function to work Select2 should be attached to a input type='hidden' tag instead of a select.




dataarray/object
    Options for the built in query function that works with arrays.
    
If this element contains an array, each element in the array must contain id and text keys

    
Alternatively, this element can be specified as an object in which results key must contain the data as an array and a text key can either be the name of the key in data items that contains text or a function that retrieves the text given a data element from the array




tagsarray/function
    Puts Select2 into 'tagging'mode where the user can add new choices and pre-existing tags are provided via
    this options attribute which is either an array or a function that returns an
    array of objects or strings. If strings are used instead of objects
    they will be converted into an object that has an id and text attribute equal
    to the value of the string.







    
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.



    

        ParameterTypeDescription
    

    
value (optional)object

        

            

                Single-ValuedMulti-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.
            


        



    



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




    
destroy




Reverts changes to DOM done by Select2. Any selection done via Select2 will be preserved.




    
open




Opens the dropdown



    
close




Closes the dropdown



    
disable




Disables Select2. During this mode the user is not allowed to manipulate the selection.



    
enable




Enables Select2.




    
container




Retrieves the main container element that wraps all of DOM added by Select2
    Example: console.log($("#tags").select2("container"));



    
onSortStart




Notifies Select2 that a drag and drop sorting operation has started. Select2 will hide all non-selection list items such as the search container, etc.
    Example: $("#tags").select2("onSortStart");



    
onSortEnd




Notifies Select2 that a drag and drop sorting operation has finished. Select2 will re-display any elements previously hidden and update the selection of the element it is attached to.
    Example: $("#tags").select2("onSortEnd");






    
Events






    

        
change

        
Fired when selection is changed.

        
This event is not fired when the selection is changed using Select2's val() method.