Select2 supports a small subset of options in every build that is generated. Each option typically has a decorator that is required that wraps an adapter, adding support for the option. This is only required when a custom adapter is being used, as Select2 will build the required adapters by default.

Display

Placeholders

Select2 can display a placeholder for a single-value select that will replace an option, or be shown when no options are selected for multiple-value selects. You can find an example on the example page.

Key: placeholder
Value: string or object

Adapter: SelectionAdapter
Decorator: Placeholder

Heads up! Because browsers assume that the first option in single-value select boxes is selected, you must add an empty <option></option> tag that the placeholder should use, or it will not work.

If the value is a string, the placeholder will be displayed when a blank option is used as the placeholder. The value will be the message to show to users as the placeholders.

If the value is an object, the object should be compatible with Select2's internal objects. The id should be the id to look for when determining if the placeholder should be displayed. The text should be the placeholder to display when that option is selected.

You pass in an object when you are using a framework that creates its own placeholder option. The id should be the same as the value attribute on the option.

Internationalization (Language support)

Messages will be displayed to users when necessary, such as when no search results were found or more characters need to be entered in order for a search to be made. These messages have been translated into many languages by contributors to Select2, but you can also provide your own translations.

Key: language
Value: object or string

Module: Translation

Heads up! When using translations provided by Select2, you must make sure to include the translation file in your page after Select2.

When a string is passed in as the language, Select2 will try to resolve it into a language file. This allows you to specify your own language files, which must be defined as an AMD module. If the language file cannot be found, Select2 will assume it is a language code controlled by Select2, and it will try to load the translations for that language instead.

You can include your own translations by providing an object similar to the one below.

language: {
  // You can find all of the options in the language files provided in the
  // build. They all must be functions that return the string that should be
  // displayed.
  inputTooShort: function () {
    return "You must enter more characters...";
  }
}

Results

Select2 can work on many different data sets ranging from local options, the same way that a <select> typically works, from remove options where a server generates the results that users can select from.

Array

Select2 allows creating the results based on an array of data objects that is included when initializing Select2.

Key: data
Value: array of objects

Adapter: ArrayAdapter

The objects that the users can select from should be passed as an array with each object containing id and text properties.

AJAX

Select2 allows searching for results from remote data sources using AJAX requests.

Key: ajax
Value: object

Adapter: AjaxAdapter

All options passed to this option will be directly passed to the $.ajax function that executes AJAX requests. There are a few custom options that Select2 will intercept, allowing you to customize the request as it is being made.

ajax: {
  // The number of milliseconds to wait for the user to stop typing before
  // issuing the ajax request.
  delay: 250,
  // You can craft a custom url based on the parameters that are passed into the
  // request. This is useful if you are using a framework which has
  // JavaScript-based functions for generating the urls to make requests to.
  //
  // @param params The object containing the parameters used to generate the
  //   request.
  // @returns The url that the request should be made to.
  url: function (params) {
    return UrlGenerator.Random();
  },
  // You can pass custom data into the request based on the parameters used to
  // make the request. For `GET` requests, the default method, these are the
  // query parameters that are appended to the url. For `POST` requests, this
  // is the form data that will be passed into the request. For other requests,
  // the data returned from here should be customized based on what jQuery and
  // your server are expecting.
  //
  // @param params The object containing the parameters used to generate the
  //   request.
  // @returns Data to be directly passed into the request.
  data: function (params) {
    var queryParameters = {
      q: params.term
    }

    return queryParameters;
  },
  // You can modify the results that are returned from the server, allowing you
  // to make last-minute changes to the data, or find the correct part of the
  // response to pass to Select2. Keep in mind that results should be passed as
  // an array of objects.
  //
  // @param data The data as it is returned directly by jQuery.
  // @returns An array of objects that will be rendered by Select2.
  processResults: function (data) {
    return data;
  }
}

Core options