Select2 #
Find similar titles

Structured data

Category: Programming

Multiple select boxes #

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

Example code #

Placeholders #

  <p>
    A placeholder value can be defined and will be displayed until a selection is made.
  </p>

  <p>
    <select class="js-example-placeholder-single js-states form-control">
      <option></option>
    </select>
  </p>

  <p>
    Select2 uses the <code>placeholder</code> attribute on multiple select
    boxes, which requires IE 10+. You can support it in older versions with
    <a href="https://github.com/jamesallardice/Placeholders.js">the Placeholders.js polyfill</a>.
  </p>

  <p>
    <select class="js-example-placeholder-multiple js-states form-control" multiple="multiple"></select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-placeholder"></pre>

</div>

Templating #

  <p>
    Various display options of the Select2 component can be changed
  </p>

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

  <p>
    You can access the <code><option></code> element
    (or <code><optgroup></code>) and any attributes on those elements
    using <code>.element</code>.
  </p>

  <p>
    Templating is primarily controlled by the
    <a href="options.html#templateResult"><code>templateResult</code></a>
    and <a href="options.html#templateSelection"><code>templateSelection</code></a>
    options.
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-templating"></pre>

</div>

Loading array data #

  <p>
    Select2 provides a way to load the data from a local array.
  </p>

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

  <p>
    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.
  </p>

  <p>
    <select class="js-example-data-array-selected form-control">
      <option value="2" selected="selected">duplicate</option>
    </select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-data-array"></pre>

</div>

Loading remote data #

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

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

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

  <pre data-fill-from=".js-code-data-ajax-html"></pre>

  <p>
    You can configure how Select2 searches for remote data using the
    <code>ajax</code> option. More information on the individual options
    that Select2 handles can be found in the
    <a href="options.html#ajax">options documentation for <code>ajax</code></a>.
  </p>

  <pre data-fill-from=".js-code-data-ajax"></pre>

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

</div>

Responsive design - Percent width #

  <p>
    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.
  </p>

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

  <p>
    <select class="js-example-responsive js-states" multiple="multiple" style="width: 75%"></select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-responsive"></pre>

  <div class="alert alert-warning">
    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
    <code>style</code> declaration into the tag.
  </div>

</div>

Disabled mode #

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

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

  <p>
    <select class="js-example-disabled-multi js-states form-control" multiple="multiple" disabled="disabled"></select>
  </p>

  <p>
    <button class="js-programmatic-enable btn btn-primary">
      Enable
    </button>
    <button class="js-programmatic-disable btn btn-warning">
      Disable
    </button>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-disabled"></pre>

</div>

Disabled results #

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

  <p>
    <select class="js-example-disabled-results form-control">
      <option value="one">First</option>
      <option value="two" disabled="disabled">Second (disabled)</option>
      <option value="three">Third</option>
    </select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-disabled-results"></pre>

</div>

Programmatic access #

  <p>
    Select2 supports methods that allow programmatic control of the
    component.
  </p>

  <p>
    <button class="js-programmatic-set-val btn btn-primary">
      Set to California
    </button>

    <button class="js-programmatic-open btn btn-success">
      Open
    </button>

    <button class="js-programmatic-close btn btn-success">
      Close
    </button>

    <button class="js-programmatic-init btn btn-danger">
      Init
    </button>

    <button class="js-programmatic-destroy btn btn-danger">
      Destroy
    </button>
  </p>

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

  <p>
    <button class="js-programmatic-multi-set-val btn btn-primary">
      Set to California and Alabama
    </button>

    <button class="js-programmatic-multi-clear btn btn-primary">
      Clear
    </button>
  </p>

  <p>
    <select class="js-example-programmatic-multi js-states form-control" multiple="multiple"></select>
  </p>

</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-programmatic"></pre>

</div>

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 maxSelectionLength in the select2 options

  <p>
    <select class="js-example-basic-multiple-limit js-states form-control" multiple="multiple"></select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-multiple-limit"></pre>

</div>

Hiding the search box #

  <p>
    Select2 allows you to hide the search box depending on the numbeer of
    options which are displayed. In this example, we use the value
    <code>Infinity</code> to tell Select2 to never display the search box.
  </p>

  <p>
    <select class="js-example-basic-hide-search js-states form-control"></select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-hide-search"></pre>

</div>

Events #

  <p>
    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
    <a href="options.html#events">on the options page</a>.
  </p>

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

  <p>
    <select class="js-states js-example-events form-control" multiple="multiple"></select>
  </p>

  <p>
    <code>change</code> is fired whenever an option is selected or removed.
  </p>

  <p>
    <code>select2:open</code> is fired whenever the dropdown is opened.
    <code>select2:opening</code> is fired before this and can be prevented.
  </p>

  <p>
    <code>select2:close</code> is fired whenever the dropdown is closed.
    <code>select2:closing</code> is fired before this and can be prevented.
  </p>

  <p>
    <code>select2:select</code> is fired whenever a result is selected.
    <code>select2:selecting</code> is fired before this and can be prevented.
  </p>

  <p>
    <code>select2:unselect</code> is fired whenever a result is unselected.
    <code>select2:unselecting</code> is fired before this and can be prevented.
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <ul class="js-event-log"></ul>

  <pre data-fill-from=".js-code-events"></pre>

</div>

Tagging support #

  <p>
    Select2 can be used to quickly set up fields used for tagging.
  </p>

  <p>
    <select class="js-example-tags form-control" multiple="multiple">
      <option selected="selected">orange</option>
      <option>white</option>
      <option selected="selected">purple</option>
    </select>
  </p>

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

</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-tags"></pre>

</div>

Automatic tokenization #

  <p>
    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.
  </p>

  <p>
    <select class="js-example-tokenizer form-control" multiple="multiple">
      <option>red</option>
      <option>blue</option>
      <option>green</option>
    </select>
  </p>

  <p>
    The separators that should be used when tokenizing can be specified
    using the <a href="options.html#tokenSeparators">tokenSeparators</a>
    options.
  </p>

</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-tokenizer"></pre>

</div>

Custom matcher #

  <p>
    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:
  </p>

  <p>
    <select class="js-example-matcher-start js-states form-control"></select>
  </p>

  <p>
    This custom matcher uses a
    <a href="options.html#compat-matcher">compatibility module</a> that is
    only bundled in the
    <a href="index.html#builds-full">full version of Select2</a>. You also
    have the option of using a
    <a href="options.html#matcher">more complex matcher</a>.
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-matcher-start"></pre>

</div>

Diacritics support #

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

  <p>
    <select class="js-example-diacritics form-control">
      <option>Aeróbics</option>
      <option>Aeróbics en Agua</option>
      <option>Aerografía</option>
      <option>Aeromodelaje</option>
      <option>Águilas</option>
      <option>Ajedrez</option>
      <option>Ala Delta</option>
      <option>Álbumes de Música</option>
      <option>Alusivos</option>
      <option>Análisis de Escritura a Mano</option>
    </select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-diacritics"></pre>

</div>

Multiple languages #

  <p>
    Select2 supports displaying the messages in different languages, as well
    as providing your own
    <a href="options.html#language">custom messages</a>
    that can be displayed.
  </p>

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

  <p>
    The language does not have to be defined when Select2 is being
    initialized, but instead can be defined in the <code>[lang]</code>
    attribute of any parent elements as <code>[lang="es"]</code>.
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-language"></pre>

</div>

Theme support #

  <p>
    Select2 supports custom themes using the
    <a href="options.html#theme">theme option</a>
    so you can style Select2 to match the rest of your application.
  </p>

  <p>
    <select class="js-example-theme-single js-states form-control">
    </select>
  </p>

  <p>
    These are using the <code>classic</code> theme, which matches the old
    look of Select2.
  </p>

  <p>
    <select class="js-example-theme-multiple js-states form-control" multiple="multiple"></select>
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-theme"></pre>

</div>

RTL support #

  <p>
    Select2 will work on RTL websites if the <code>dir</code> attribute is
    set on the <code><select></code> or any parents of it.
  </p>

  <p>
    <select class="js-example-rtl js-states form-control" dir="rtl"></select>
  </p>

  <p>
    You can also use initialize Select2 with <code>dir: "rtl"</code> set.
  </p>
</div>
<div class="col-md-8">
  <h2>Example code</h2>

  <pre data-fill-from=".js-code-rtl"></pre>

</div>