select2/pages/01.getting-started/02.basic-usage/docs.md

---
title: Basic usage
taxonomy:
    category: docs
process:
    twig: true
never_cache_twig: true
---

## Single select boxes

Select2 was designed to be a replacement for the standard `<select>` box that is displayed by the browser.  By default it supports all options and operations that are available in a standard select box, but with added flexibility.

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

<select class="js-states form-control"></select>

and turn it into this...

<div class="s2-example">
    <select class="js-example-basic-single js-states form-control"></select>
</div>

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

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

Select2 will register itself as a jQuery function if you use any of the distribution builds, so you can call `.select2()` on any jQuery selector where you would like to initialize Select2.

```
$('.js-example-basic-single').select2();
```

## Multi-select boxes (pillbox)

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

<div class="s2-example">
  <p>
    <select class="js-example-basic-multiple js-states form-control" multiple="multiple"></select>
  </p>
</div>

```
<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>
```

<script type="text/javascript">
  $.fn.select2.amd.require([
    "select2/core",
    "select2/utils"
  ], function (Select2, Utils, oldMatcher) {
    var $basicSingle = $(".js-example-basic-single");
    var $basicMultiple = $(".js-example-basic-multiple");

    $.fn.select2.defaults.set("width", "100%");

    $basicSingle.select2();
    $basicMultiple.select2();

    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;
    };
  });

</script>