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.
+ $("#e2_2").select2({ + placeholder: "Select a State" + }); + }); + +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:
-
-
-
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:
-
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>
@@ -475,836 +475,834 @@ function format(state) {
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 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 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.
-- -
-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.
++ +
+
- 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:
- -
+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:
+ +
-
- 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 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
-- - - - - - - -
-
-
-
- - - - - - - -
-
-
-
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
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
+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.
-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 be set a limit on the number of characters that can be entered per tag.
+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.
-You would not be able to enter any input of more than 10 characters long.
+
- 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
+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.
-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.
+
- 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 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.
+ 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
-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`.
--
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.
-
-
-
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`.
++
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.
+
+
+
- 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.
-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.
+
-
- 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.
-
- -
-
+ 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.
+
+ +
+
- | Parameter | Type | Description | -||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| width | string |
- Controls the width style attribute of the Select2 container div. The following values are supported:
-
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| minimumInputLength | int | Number of characters necessary to start a search | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maximumInputLength | int | Maximum number of characters that can be entered for an input | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. - -The option can be set to a Only applies to single-value select boxes - |
- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maximumSelectionSize | int/function |
- - The maximum number of items that can be selected in a multi-select control. If this number is less than 1 selection is not limited. - -Once the number of selected items reaches the maximum specified the contents of the dropdown will be populated
- by the |
- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| placeholder | string |
- Initial value that is selected if no other selection is made. -The placeholder can also be specified as a
+
+Constructor
+
+valGets or sets the selection. If the
-
- valGets or sets the selection. If the
alert("Selected value is: "+$("#e8").select2("val")); $("#e8").select2("val", "CA");
- Notice that in order to use this method you must define the
-
- dataGets or sets the selection. Analogous to
+
+dataGets or sets the selection. Analogous to
-
- destroyReverts changes to DOM done by Select2. Any selection done via Select2 will be preserved. +
+
+destroyReverts changes to DOM done by Select2. Any selection done via Select2 will be preserved. -
-
- openOpens the dropdown -
-
- closeCloses the dropdown -
-
- searchOpens the dropdown, sets the value of the input, and updates the results list.
- Example:
-
- enable(boolean)Enables or disables Select2 and its underlying form component based on the boolean parameter. -
-
- readonly(boolean)Toggles readonly mode on Select2 and its underlying form component based on the boolean parameter. +
+
+openOpens the dropdown +
+
+closeCloses the dropdown +
+
+enable(boolean)Enables or disables Select2 and its underlying form component based on the boolean parameter. +
+
+readonly(boolean)Toggles readonly mode on Select2 and its underlying form component based on the boolean parameter. -
+ containerRetrieves the main container element that wraps all of DOM added by Select2
+ Example:
+
+onSortStartNotifies 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:
+
+onSortEndNotifies 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:
+
+
+Events
+
+
- change+Fired when selection is changed. +The event object contains the following custom properties: +
Retrieves the main container element that wraps all of DOM added by Select2
- Example:
-
+onSortStart
+
+
- select2-opening+Fired before the dropdown is shown. +The event listener can prevent the opening by calling 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:
-
+onSortEnd
+
+
- select2-open+Fired after the dropdown is shown. +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:
-
-
- Events
-
-
-
- change-Fired when selection is changed. -The event object contains the following custom properties: -
-
-
-
- select2-opening-Fired before the dropdown is shown. -The event listener can prevent the opening by calling
-
-
-
- select2-open-Fired after the dropdown is shown. - -
-
-
-
- select2-highlight-Fired when a choice is highlighted in the dropdown. - -The event object contains the following custom properties: -
-
-
-
- select2-selecting-Fired when a choice is being selected in the dropdown, but before any modification has been made to the selection.
- This event is used to allow the user to reject selection by calling The event object contains the following custom properties: -
-
-
-
- select2-removed-Fired when a choice is removed or cleared - -The event object contains the following custom properties: -
-
-
-
- select2-loaded-Fired when query function is done loading the data and the results list has been updated - -The event object contains the following custom properties: -
-
-
-
- select2-focus-Fired when the control is focussed - -
-
-
-
-
-
- select2-blur-Fired when the control is blurred - -
-
+
-
+Configuring Defaults- Select2 exposes its default options via the$.fn.select2.defaults object. Properties changed in this object (same properties configurable through the constructor) will take effect for every instance created after the change
-
-
+
+
+
+select2-highlight+Fired when a choice is highlighted in the dropdown. + +The event object contains the following custom properties: +
+
+
+
+select2-selecting+Fired when a choice is being selected in the dropdown, but before any modification has been made to the selection.
+ This event is used to allow the user to reject selection by calling The event object contains the following custom properties: +
+
+
+
+select2-removed+Fired when a choice is removed or cleared + +The event object contains the following custom properties: +
+
+
+
+select2-loaded+Fired when query function is done loading the data and the results list has been updated + +The event object contains the following custom properties: +
+
+
+
+select2-focus+Fired when the control is focussed + +
+
+
+
+
+
+select2-blur+Fired when the control is blurred + +
+
+
+Configuring Defaults+ Select2 exposes its default options via the$.fn.select2.defaults object. Properties changed in this object (same properties configurable through the constructor) will take effect for every instance created after the change
+
+ |