Select2 3.5.4版本

off

No width attribute will be set. Keep in mind that the container div copies classes from the source element so setting the width attribute may not always be necessary.

element

Uses javascript to calculate the width of the source element.

copy

Copies the value of the width style attribute set on the source element.

resolve

First attempts to copy than falls back on element.

other values

if the width attribute contains a function it will be evaluated, otherwise the value is used verbatim.

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 negative value to permanently hide the search field.

Only applies to single-value select boxes

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 formatSelectionTooBig function.

Initial value that is selected if no other selection is made.

The placeholder can also be specified as a data-placeholder attribute on the select or input element that Select2 is attached to.

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 attached to a select resolves the option that should be used as the placeholder. Can either be a function which given the select element should return the option element or a string first to indicate that the first option should be used.

This option is useful when Select2's default of using the first option only if it has no value and no text is not suitable.

Separator character or string used to delimit ids in value attribute of the multi-valued selects. The default delimiter is the , character.

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.

This option only works 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.

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.

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

Only applies when configured in multi-select mode.

If set to true the dropdown is opened when the user presses the enter key and Select2 is closed. By default this option is enabled.

id(object)

matcher(term, text, option)

sortResults(results, container, query)

formatSelection(object, container)

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

The implementation may choose to append elements directly to the provided container object, or return a single value and have it automatically appended.

When attached to a select the 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(object, container, query)

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

The implementation may choose to append elements directly to the provided container object, or return a single value and have it automatically appended.

When attached to a select the 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
}

formatResultCssClass(object)

By default when attached to a select css classes from options will be automatically copied.

formatNoMatches(term)

formatSearching()

formatAjaxError(jqXHR, textStatus, errorThrown)

For more info on the parameters, refer to the JQuery API Documentation.

formatInputTooShort(term, minLength)

formatInputTooLong(term, maxLength)

formatSelectionTooBig(maxSize)

formatLoadMore(pageNumber)

createSearchChoice(term)

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.

top

Insert in the top of the list

bottom

Insert at the end of the list

<function>

A custom function. For example if you want to insert the new item in the second position:

$("#tags").select2({
    ...
    createSearchChoice: function(term) { ... },
    createSearchChoicePosition: function(list, item) {
        list.splice(1, 0, item);
    }
});

Essentially this is an id->object mapping function.

initSelection(element, callback)

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

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

// Or for single select elements:
$("#select").select2({
    initSelection : function (element, callback) {
        var data = {id: element.val(), text: element.val()};
        callback(data);
    }
});

Tokenizer only applies to multi-selects.

tokenizer(input, selection, selectCallback, opts)

query(options)

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

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" }
        ] }
    ]
}
                        

data(term, page)

results(data, page, query)

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

For documentation of the data format see the query function.

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.

adaptContainerCssClass(clazz)

adaptDropdownCssClass(clazz)

Function used to post-process markup returned from formatter functions. By default this function escapes html entities to prevent javascript injection.

Set to true if you want Select2 to select the currently highlighted option when it is blurred.

Function used to determine what the next search term should be.

Here is an example implementation used to display the current search term when the dropdown is opened:

function displayCurrentValue(selectedObject, 
currentSearchTerm) {
    return currentSearchTerm;
}

$("#e1").select2({
    nextSearchTerm: displayCurrentValue
});

Function can be used when the dropdown is configured in single and multi-select mode. It is triggered after selecting an item. In single mode it is also triggered after initSelection (when provided).