+
+ | 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 | object/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.
+
+
+
+ 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.
+
+ |
+
+ | 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)
+
+ | Parameter | Type | Description |
|---|
+ | object | object | A choice object |
+ | <returns> | string | the id of the object |
+
+ The default implementation expects the object to have a id property that is returned.
+ |
+ | formatSelection | function |
+ Function used to 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 |
+
+ |
+ | 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)
+
+ | Parameter | Type | Description |
|---|
+ | term | string | Search 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
+ |
+ | 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 id->object mapping function.
+
+ initSelection(element)
+
+ | Parameter | Type | Description |
|---|
+ | element | jQuery array | element Select2 is attached to |
+ | <returns> | object or array of objects | Object 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)
+
+ | Parameter | Type | Description |
|---|
+ | options.term | string | Search string entered by user |
+ | options.page | int | 1-based page number tracked by Select2 for use with infinite scrolling of results |
+ | options.callback | function |
+ Callback function that should be called with the result object. The result 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.more | boolean | trueif more results are available for the current search term |
+
+ |
+
+ In order for this function to work Select2 should be attached to a input type='hidden' tag instead of a select.
+ |
+
+ | 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.
+
+
+ | Parameter | Type | Description |
|---|
+ | transport | function | Function 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. |
+ | 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, page)
+
+ | Parameter | Type | Description |
|---|
+ | term | string | Search term |
+ | page | int | 1-based page number tracked by Select2 for use with infinite scrolling of results |
+ | <returns> | object | Object containing url paramters |
+
+ |
+ | results | function |
+ Function used to build the query results object from the ajax response
+ results(data, page)
+
+ | Parameter | Type | Description |
|---|
+ | data | object | Retrieved data |
+ | page | int | Page number that was passed into the data function above |
+ | <returns> | object | Results 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.
+ |
+ | 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 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
+ |
+ | 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.
+ Reverts changes to DOM done by Select2. Any selection done via Select2 will be preserved.
+
+ 