Single select boxes

Select2 can take a regular select box like this...

and turn it into this...






1
2
3
4
5
6
7
8
9
10
11

<script type="text/javascript">
$(document).ready(function() {
  $(".js-example-basic-single").select2();
});
</script>

<select class="js-example-basic-single">
  <option value="AL">Alabama</option>
    ...
  <option value="WY">Wyoming</option>
</select>

Multiple select boxes

Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute.






1
2
3
4
5
6
7
8
9

<script type="text/javascript">
$(".js-example-basic-multiple").select2();
</script>

<select class="js-example-basic-multiple" multiple="multiple">
  <option value="AL">Alabama</option>
    ...
  <option value="WY">Wyoming</option>
</select>

Select boxes with labels

You can, and should, use a <label> with Select2, just like any other <select> element.

Click this to focus the single select element

Click this to focus the multiple select element






1
2
3
4
5
6
7
8
9
10
11

<label for="id_label_single">
  Click this to highlight the single select element

  <select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
</label>

<label for="id_label_multiple">
  Click this to highlight the multiple select element

  <select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
</label>

Placeholders

A placeholder value can be defined and will be displayed until a selection is made. Select2 uses the placeholder attribute on multiple select boxes, which requires IE 10+. You can support it in older versions with the Placeholders.js polyfill.

In addition to handling options from a standard <select>, Select2 can also retrieve the results from other data sources.

Loading array data

Select2 provides a way to load the data from a local array. You can provide initial selections with array data by providing the option tag for the selected values, similar to how it would be done for a standard select.






1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<script type="text/javascript">
var data = [{ id: 0, text: 'enhancement' }, { id: 1, text: 'bug' }, { id: 2, text: 'duplicate' }, { id: 3, text: 'invalid' }, { id: 4, text: 'wontfix' }];

$(".js-example-data-array").select2({
  data: data
})

$(".js-example-data-array-selected").select2({
  data: data
})
</script>

<select class="js-example-data-array"></select>

<select class="js-example-data-array-selected">
  <option value="2" selected="selected">duplicate</option>
</select>

Loading remote data

Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API.

When using Select2 with remote data, the HTML required for the select is the same as any other Select2. If you need to provide default selections, you just need to include an option for each selection that contains the value and text that should be displayed.






1
2
3

<select class="js-data-example-ajax">
  <option value="3620194" selected="selected">select2/select2</option>
</select>

You can configure how Select2 searches for remote data using the ajax option. More information on the individual options that Select2 handles can be found in the options documentation for ajax.






1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

$(".js-data-example-ajax").select2({
  ajax: {
    url: "https://api.github.com/search/repositories",
    dataType: 'json',
    delay: 250,
    data: function (params) {
      return {
        q: params.term, // search term
        page: params.page
      };
    },
    processResults: function (data, params) {
      // parse the results into the format expected by Select2
      // since we are using custom formatting functions we do not need to
      // alter the remote JSON data, except to indicate that infinite
      // scrolling can be used
      params.page = params.page || 1;

      return {
        results: data.items,
        pagination: {
          more: (params.page * 30) < data.total_count
        }
      };
    },
    cache: true
  },
  escapeMarkup: function (markup) { return markup; }, // let our custom formatter work
  minimumInputLength: 1,
  templateResult: formatRepo, // omitted for brevity, see the source of this page
  templateSelection: formatRepoSelection // omitted for brevity, see the source of this page
});

Select2 will pass any options in the ajax object to jQuery's $.ajax function, or the transport function you specify.

Disabled mode

Select2 will respond to the disabled attribute on <select> elements. You can also initialize Select2 with disabled: true to get the same effect.

Disabled results

Select2 will correctly handle disabled results, both with data coming from a standard select (when the disabled attribute is set) and from remote sources, where the object has disabled: true set.






1
2
3
4
5

<select class="js-example-disabled-results">
  <option value="one">First</option>
  <option value="two" disabled="disabled">Second (disabled)</option>
  <option value="three">Third</option>
</select>

Limiting the number of selections

Select2 multi-value select boxes can set restrictions regarding the maximum number of options selected. The select below is declared with the multiple attribute with maximumSelectionLength in the select2 options.






1
2
3

$(".js-example-basic-multiple-limit").select2({
  maximumSelectionLength: 2
});

Hiding the search box

Select2 allows you to hide the search box depending on the number of options which are displayed. In this example, we use the value Infinity to tell Select2 to never display the search box.






1
2
3

$(".js-example-basic-hide-search").select2({
  minimumResultsForSearch: Infinity
});

DOM events

Select2 will trigger some events on the original select element, allowing you to integrate it with other components. You can find more information on events on the options page.

change is fired whenever an option is selected or removed.

select2:open is fired whenever the dropdown is opened. select2:opening is fired before this and can be prevented.

select2:close is fired whenever the dropdown is closed. select2:closing is fired before this and can be prevented.

select2:select is fired whenever a result is selected. select2:selecting is fired before this and can be prevented.

select2:unselect is fired whenever a result is unselected. select2:unselecting is fired before this and can be prevented.

Programmatic access

Select2 supports methods that allow programmatic control of the component.

Tagging support

In addition to the dropdown menu of options, Select2 can also allow free-text responses. This feature is called "tagging". To enable free-text responses, set the tags option to true:






1
2
3

$(".js-example-tags").select2({
  tags: true
})

Note that when tagging is enabled the user can select from the pre-existing options or create a new option by picking the first choice, which is what the user has typed into the search box so far.

Tagging with multi-value select boxes

Tagging can also be used in multi-value select boxes. In the example below, we set the multiple="multiple" attribute on a Select2 control that also has tags: true enabled:

Try entering a value that isn't listed in the dropdown - you'll be able to add it as a new option!

Automatic tokenization

Select2 supports ability to add choices automatically as the user is typing into the search field. Try typing in the search field below and entering a space or a comma.

The separators that should be used when tokenizing can be specified using the tokenSeparators options.






1
2
3
4

$(".js-example-tokenizer").select2({
  tags: true,
  tokenSeparators: [',', ' ']
})

Customizing how results are matched

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:

This custom matcher uses a compatibility module that is only bundled in the full version of Select2. You also have the option of using a more complex matcher.






1
2
3
4
5
6
7
8
9
10
11
12
13

function matchStart (term, text) {
  if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
    return true;
  }

  return false;
}

$.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
  $(".js-example-matcher-start").select2({
    matcher: oldMatcher(matchStart)
  })
});

Multiple languages

Select2 supports displaying the messages in different languages, as well as providing your own custom messages that can be displayed.

The language does not have to be defined when Select2 is being initialized, but instead can be defined in the [lang] attribute of any parent elements as [lang="es"].






1
2
3

$(".js-example-language").select2({
  language: "es"
});

RTL support

Select2 will work on RTL websites if the dir attribute is set on the <select> or any parents of it. You can also initialize Select2 with dir: "rtl" set.






1
2
3

$(".js-example-rtl").select2({
  dir: "rtl"
});

Diacritics support

Select2's default matcher will ignore diacritics, making it easier for users to filter results in international selects. Type "aero" into the select below.






1

$(".js-example-diacritics").select2();

Theme support

Select2 supports custom themes using the theme option so you can style Select2 to match the rest of your application.

These are using the classic theme, which matches the old look of Select2.






1
2
3
4
5
6
7

$(".js-example-theme-single").select2({
  theme: "classic"
});

$(".js-example-theme-multiple").select2({
  theme: "classic"
});

Templating

Various display options of the Select2 component can be changed: You can access the <option> element (or <optgroup>) and any attributes on those elements using .element.

Templating is primarily controlled by the templateResult and templateSelection options.






1
2
3
4
5
6
7
8
9
10
11
12

function formatState (state) {
  if (!state.id) { return state.text; }
  var $state = $(
    '<span><img src="vendor/images/flags/' + state.element.value.toLowerCase() + '.png" class="img-flag" /> ' + state.text + '</span>'
  );
  return $state;
};

$(".js-example-templating").select2({
  templateResult: formatState,
  templateSelection: formatState
});

Responsive design - Percent width

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.






1
2

<select class="js-example-responsive" style="width: 50%"></select>
<select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>

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.

Examples

The basics