body and is absolutely positioned. This should help when Select2 is inside constrained elements such as modals.initSeletion has changed to support asynchronous requestsSelect2 can take a regular select box like this:
and turns it into:
with support for quick option filtering via a search box
<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>
Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute. Select2 automatially picks up on this:
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.
Select2 supports a minimum input setting which is useful for large remote datasets where short search terms are not very useful:
Various display options of the Select2 component can be changed:
You can set data- attributes to <option> (or <optgroup>) and use them inside temptlating 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;
}
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.
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:
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.
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 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.
Select2 supports methods that allow programmatic control of the component
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
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.
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.
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.
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
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.
| Parameter | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| minimumInputLength | int | Number of characters necessary to start a search | |||||||||||||||||||||||||||||||||||||||||||||||||||
| minimumResultsForSearch | int |
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 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
| placeholder | string |
Initial value that is selected if no other selection is made. The placeholder can also be specified as a Note that because browsers assume the first | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 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 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. |
|||||||||||||||||||||||||||||||||||||||||||||||||||
| id | function |
Function used to get the id from the choice object or a string representing the key under which the id is stored.
id(object)
id property that is returned.
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| matcher | function |
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)
function(term, text) { return text.toUpperCase().indexOf(term.toUpperCase())>0; }
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| formatSelection | function |
Function used to render the current selection.
formatSelection(object)
text property that is returned.
Original <option> (or <optgroup>) element is accessible inside the specified function through the property item.element:
format(item) {
var originalOption = item.element;
// return item.text
}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| formatResult | function |
Function used to render a result that the user can select.
formatResult(object)
text property that is returned.
Original <option> (or <optgroup>) element is accessible inside the specified function through the property item.element:
format(item) {
var originalOption = item.element;
// return item.text
}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| formatNoMatches | function |
Function used to render the "No matches" message
formatNoMatches(term)
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| formatInputTooShort | function |
Function used to render the "Search input too short" message
formatInputTooShort(term, minLength)
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| createSearchChoice | function |
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)
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| initSelection | function |
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 initSelection(element, callback)
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, callback) {
var data = [];
$(element.val().split(",")).each(function () {
data.push({id: this, text: this});
});
callback(data);
}
});
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| query | function |
Function used to query results for the search term.
query(options)
In order for this function to work Select2 should be attached to a
Example Data
{
more: false,
results: [
{ id: "CA", text: "California" },
{ id: "AL", text: "Alabama" }
]
}
Example Hierarchical Data
{
more: false,
results: [
{ text: "Western", children: [
{ id: "CA", text: "California" },
{ id: "AZ", text: "Arizona" }
] },
{ text: "Eastern", children: [
{ id: "FL", text: "Florida" }
] }
]
}
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
| ajax | object |
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.
In order for this function to work Select2 should be attached to a | |||||||||||||||||||||||||||||||||||||||||||||||||||
| data | array/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 Alternatively, this element can be specified as an object in which | |||||||||||||||||||||||||||||||||||||||||||||||||||
| tags | array/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.
|
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 |
|
alert("Selected value is: "+$("#e8").select2("val")); $("#e8").select2("val", {id:"CA", text:"Califoria"});
Gets or sets the selection. Analogous to val method, but works with objects instead of ids.
Reverts changes to DOM done by Select2. Any selection done via Select2 will be preserved.
Opens the dropdown
Closes the dropdown
Disables Select2. During this mode the user is not allowed to manipulate the selection.
Enables Select2.
Retrieves the main container element that wraps all of DOM added by Select2
Example: console.log($("#tags").select2("container"));
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");
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");
Fired when selection is changed.
This event is not fired when the selection is changed using Select2's val() method.
The event object contains the following custom properties:
Fired when the dropdown is shown.
The event listener can prevent the opening by calling preventDefault() on the supplied event object.