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.

Select2 will automatically apply decorators to any adapters which have not been manually overriden. The only time you need to decorate adapters is when you are using third-party adapters not provided by Select2, or you are using features not provided in the Select2 core. You can apply a decorator to an adapter using the Utils.Decorate method provided with Select2.

$.fn.select2.amd.require(
    ["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
    function (Utils, SingleSelection, Placeholder) {
  var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
});

All core options that use decorators or adapters will clearly state it in the "Decorator" or "Adapter" part of the documentation. Decorators are typically only compatible with a specific type of adapter, so make sure to note what adapter is given.

Declaring configuration in the `data-*` attributes

It is recommended that you declare your configuration options for Select2 when initializing Select2. You can also define your configuration options by using the HTML5 data-* attributes, which will override any options set when initializing Select2 and any defaults.

This means that if you declare your <select> tag as...

<select data-tags="true" data-placeholder="Select an option"></select>

Will be interpreted the same as initializing Select2 as...

$("select").select2({
  tags: "true",
  placeholder: "Select an option"
});

You can also define nested configurations, which are typically needed for options such as AJAX. Each level of nesting should be separated by two dashes (--) instead of one.

<select data-ajax--url="http://example.org/api/test" data-ajax--cache="true"></select>

Which will be interpreted the same as initializing Select2 with...

  $("select").select2({
    ajax: {
      url: "http://example.org/api/test",
      cache: "true"
    }
  });

The value of the option is subject to jQuery's parsing rules for HTML5 data attributes.

Display

Select2 provides options that allow you to directly affect how the container that holds the current selection is displayed.

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 and HidePlaceholder

Heads up! Because browsers assume that the first option in single-value select boxes is selected, you should add an empty <option></option> tag that the placeholder should use or it may 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.

placeholder: "Select a repository",

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.

placeholder: {
  id: "-1",
  text: "Select a repository"
}

You should 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.

You can allow a selected option to be cleared back to the placeholder by enabling the allowClear option.

Key: allowClear
Value: boolean

Adapter: SelectionAdapter
Decorator: AllowClear

This will display an "x" that the user can click to clear the current selection. It is designed to be used for cases where a single selection can be made.

Multiple selections

Select2 can display either a single selection or multiple selections.

Key: multiple
Value: boolean (true or false)

This option will determine what the SelectAdapter (used by default) should use to set the value of the underlying select element. It will also determine if the MultipleSelection adapter should be used.

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 remote 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 object containing the results data as well as any required
  //   metadata that is used by plugins. The object should contain an array of
  //   data objects as the `results` key.
  processResults: function (data) {
    return {
      results: data
    };
  }
}

All adapters

All adapters must implement a set of methods that Select2 will use to display them and bind any internal events.

// The basic HTML that should be rendered by Select2. A jQuery or DOM element
// should be returned, which will automatically be placed by Select2 within the
// DOM.
//
// @returns A jQuery or DOM element that contains any elements that must be
//   rendered by Select2.
Adapter.render = function () {
  return $jq;
};

// Bind to any Select2 or DOM events.
//
// @param container The Select2 object that is bound to the jQuery element.  You
//   can listen to Select2 events with `on` and trigger Select2 events using the
//   `trigger` method.
// @param $container The jQuery DOM node that all default adapters will be
//   rendered within.
Adapter.bind = function (container, $container) { };

// Position the DOM element within the Select2 DOM container, or in another
// place. This allows adapters to be located outside of the Select2 DOM,
// such as at the end of the document or in a specific place within the Select2
// DOM node.
//
// Note: This method is not called on data adapters.
//
// @param $rendered The rendered DOM element that was returned from the call to
//   `render`. This may have been modified by Select2, but the root element
//   will always be the same.
// @param $defaultContainer The default container that Select2 will typically
//   place the rendered DOM element within. For most adapters, this is the
//   Select2 DOM element.
Adapter.position = function ($rendered, $defaultContainer) { };

// Destroy any events or DOM elements that have been created.
// This is called when `select2("destroy")` is called on an element.
Adapter.destroy = function () { };

Container (selection)

The selection is what is shown to the user as a replacement of the standard <select> box. It controls the display of the selection option(s), as well anything else that needs to be embedded within the container, such as a search box.

Key: selectionAdapter
Default: SingleSelection or MultipleSelection
Base: BaseSelection

// Update the selected data.
//
// @param data An array of data objects that have been generated by the data
//   adapter. If no objects should be selected, an empty array will be passed.
//
// Note: An array will always be passed into this method, even if Select2 is
// attached to a source which only accepts a single selection.
SelectionAdapter.update = function (data) { };

Data set

The data set is what Select2 uses to generate the possible results that can be selected, as well as the currently selected results.

Key: dataAdapter
Default: SelectAdapter
Base: BaseAdapter

// Get the currently selected options. This is called when trying to get the
// initial selection for Select2, as well as when Select2 needs to determine
// what options within the results are selected.
//
// @param callback A function that should be called when the current selection
//   has been retrieved. The first paramter to the function should be an array
//   of data objects.
DataAdapter.current = function (callback) {
  callback(currentData);
}

// Get a set of options that are filtered based on the parameters that have
// been passed on in.
//
// @param params An object containing any number of parameters that the query
//   could be affected by. Only the core parameters will be documented.
// @param params.term A user-supplied term. This is typically the value of the
//   search box, if one exists, but can also be an empty string or null value.
// @param params.page The specific page that should be loaded. This is typically
//   provided when working with remote data sets, which rely on pagination to
//   determine what objects should be displayed.
// @param callback The function that should be called with the queried results.
DataAdapter.query = function (params, callback) {
  callback(queryiedData);
}

Dropdown

The dropdown adapter defines the main container that the dropdown should be held in. It does not define any extra methods that can be used for decorators, but it is common for decorators to attach to the render and position methods to alter how the dropdown is altered and positioned.

Key: dropdownAdapter
Default: DropdownAdapter

Results

The results adapter controls the list of results that the user can select from. While the results adapter does not define any additional methods that must be implemented, it makes extensive use of the Select2 event system for cotrolling the display of results and messages.

Key: resultsAdapter
Default: ResultsAdapter

Core options

Declaring configuration in the `data-*` attributes

Display

Placeholders

Multiple selections

Internationalization (Language support)

Results

Array

AJAX

Tags

Adapters

All adapters

Container (selection)

Data set

Dropdown

Results

Core options

Declaring configuration in the data-* attributes

Display

Placeholders

Multiple selections

Internationalization (Language support)

Results

Array

AJAX

Tags

Dropdown

Attached to body

Attached below the container

Search

Adapters

All adapters

Container (selection)

Data set

Dropdown

Results

Declaring configuration in the `data-*` attributes