<!doctypehtml><html lang=en><meta charset=utf-8><title>
   Selections | Select2 - The jQuery replacement for select boxes
  </title><meta content=GravCMS name=generator><meta content="Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and pagination (infinite scrolling) of results."name=description><meta content=width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no,shrink-to-fit=no name=viewport><link title="Atom Feed"href=https://select2.org/feed:atom rel=alternate type=application/atom+xml><link title="RSS Feed"href=https://select2.org/feed:rss rel=alternate type=application/rss+xml><link href=/user/themes/site/images/favicon.png rel=icon type=image/png><link href=/assets/5ad898c30986b0985fd29e4a8ca9d1cb.css rel=stylesheet><script src=/assets/3463b090afc66f573d74febe0935c1f6.js></script><script>$(document).ready(function() {
                                anchors.options = {
                                    visible: 'hover',
                                    placement: 'right',
                                    
                                    
                                    truncate: 64
                                };
                                anchors.add('#body h2, #body h3, #body h4, #body h5');
                             });
$(document).ready(function() {
$('pre code').each(function(i, block) {
hljs.highlightBlock(block);
});
});</script><body class=searchbox-hidden data-url=/selections><select class=js-source-states><optgroup label="Alaskan/Hawaiian Time Zone"><option value=AK>Alaska<option value=HI>Hawaii<optgroup label="Pacific Time Zone"><option value=CA>California<option value=NV>Nevada<option value=OR>Oregon<option value=WA>Washington<optgroup label="Mountain Time Zone"><option value=AZ>Arizona<option value=CO>Colorado<option value=ID>Idaho<option value=MT>Montana<option value=NE>Nebraska<option value=NM>New Mexico<option value=ND>North Dakota<option value=UT>Utah<option value=WY>Wyoming<optgroup label="Central Time Zone"><option value=AL>Alabama<option value=AR>Arkansas<option value=IL>Illinois<option value=IA>Iowa<option value=KS>Kansas<option value=KY>Kentucky<option value=LA>Louisiana<option value=MN>Minnesota<option value=MS>Mississippi<option value=MO>Missouri<option value=OK>Oklahoma<option value=SD>South Dakota<option value=TX>Texas<option value=TN>Tennessee<option value=WI>Wisconsin<optgroup label="Eastern Time Zone"><option value=CT>Connecticut<option value=DE>Delaware<option value=FL>Florida<option value=GA>Georgia<option value=IN>Indiana<option value=ME>Maine<option value=MD>Maryland<option value=MA>Massachusetts<option value=MI>Michigan<option value=NH>New Hampshire<option value=NJ>New Jersey<option value=NY>New York<option value=NC>North Carolina<option value=OH>Ohio<option value=PA>Pennsylvania<option value=RI>Rhode Island<option value=SC>South Carolina<option value=VT>Vermont<option value=VA>Virginia<option value=WV>West Virginia</select><script>$(document).ready(function() {
      // Initialize "states" example
      var $states = $(".js-source-states");
      var statesOptions = $states.html();
      $states.remove();
    
      $(".js-states").append(statesOptions);
    });</script><nav id=sidebar><div id=header-wrapper><div id=header><a href=https://select2.org id=logo> <span class=logo-title> Select2 </span> </a><div class=searchbox><label for=search-by><i class="fa fa-search"> </i></label><input placeholder="Search Documentation"data-search-input=/search.json/query id=search-by><span data-search-clear> <i class="fa fa-close"> </i> </span></div></div></div><div class=scrollbar-inner><div class=highlightable><ul class=topics><li class=dd-item data-nav-id=/><a href=/> <i class="fa fa-check read-icon"> </i> <span> <b> 1. </b> Getting Started </span> </a> <ul><li class=dd-item data-nav-id=/getting-started/installation><a href=/getting-started/installation> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Installation </span> </a><li class=dd-item data-nav-id=/getting-started/basic-usage><a href=/getting-started/basic-usage> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Basic usage </span> </a><li class=dd-item data-nav-id=/getting-started/builds-and-modules><a href=/getting-started/builds-and-modules> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Builds and modules </span> </a></ul><li class=dd-item data-nav-id=/troubleshooting><a href=/troubleshooting> <i class="fa fa-check read-icon"> </i> <span> <b> 2. </b> Troubleshooting </span> </a> <ul><li class=dd-item data-nav-id=/troubleshooting/getting-help><a href=/troubleshooting/getting-help> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Getting Help </span> </a><li class=dd-item data-nav-id=/troubleshooting/common-problems><a href=/troubleshooting/common-problems> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Common problems </span> </a></ul><li class=dd-item data-nav-id=/configuration><a href=/configuration> <i class="fa fa-check read-icon"> </i> <span> <b> 3. </b> Configuration </span> </a> <ul><li class=dd-item data-nav-id=/configuration/options-api><a href=/configuration/options-api> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Options </span> </a><li class=dd-item data-nav-id=/configuration/defaults><a href=/configuration/defaults> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Global defaults </span> </a><li class=dd-item data-nav-id=/configuration/data-attributes><a href=/configuration/data-attributes> <i class="fa fa-check read-icon"> </i> <span> <b> </b> data-* attributes </span> </a></ul><li class=dd-item data-nav-id=/appearance><a href=/appearance> <i class="fa fa-check read-icon"> </i> <span> <b> 4. </b> Appearance </span> </a><li class=dd-item data-nav-id=/options><a href=/options> <i class="fa fa-check read-icon"> </i> <span> <b> 5. </b> Options </span> </a><li class=dd-item data-nav-id=/data-sources><a href=/data-sources> <i class="fa fa-check read-icon"> </i> <span> <b> 6. </b> Data sources </span> </a> <ul><li class=dd-item data-nav-id=/data-sources/formats><a href=/data-sources/formats> <i class="fa fa-check read-icon"> </i> <span> <b> </b> The Select2 data format </span> </a><li class=dd-item data-nav-id=/data-sources/ajax><a href=/data-sources/ajax> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Ajax (remote data) </span> </a><li class=dd-item data-nav-id=/data-sources/arrays><a href=/data-sources/arrays> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Arrays </span> </a></ul><li class=dd-item data-nav-id=/dropdown><a href=/dropdown> <i class="fa fa-check read-icon"> </i> <span> <b> 7. </b> Dropdown </span> </a><li class="dd-item active"data-nav-id=/selections><a href=/selections> <i class="fa fa-check read-icon"> </i> <span> <b> 8. </b> Selections </span> </a><li class=dd-item data-nav-id=/tagging><a href=/tagging> <i class="fa fa-check read-icon"> </i> <span> <b> 9. </b> Dynamic option creation </span> </a><li class=dd-item data-nav-id=/placeholders><a href=/placeholders> <i class="fa fa-check read-icon"> </i> <span> <b> 10. </b> Placeholders </span> </a><li class=dd-item data-nav-id=/searching><a href=/searching> <i class="fa fa-check read-icon"> </i> <span> <b> 11. </b> Search </span> </a><li class=dd-item data-nav-id=/programmatic-control><a href=/programmatic-control> <i class="fa fa-check read-icon"> </i> <span> <b> 12. </b> Programmatic control </span> </a> <ul><li class=dd-item data-nav-id=/programmatic-control/add-select-clear-items><a href=/programmatic-control/add-select-clear-items> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Add, select, or clear items </span> </a><li class=dd-item data-nav-id=/programmatic-control/retrieving-selections><a href=/programmatic-control/retrieving-selections> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Retrieving selections </span> </a><li class=dd-item data-nav-id=/programmatic-control/methods><a href=/programmatic-control/methods> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Methods </span> </a><li class=dd-item data-nav-id=/programmatic-control/events><a href=/programmatic-control/events> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Events </span> </a></ul><li class=dd-item data-nav-id=/i18n><a href=/i18n> <i class="fa fa-check read-icon"> </i> <span> <b> 13. </b> Internationalization </span> </a><li class=dd-item data-nav-id=/advanced><a href=/advanced> <i class="fa fa-check read-icon"> </i> <span> <b> 14. </b> Advanced </span> </a> <ul><li class=dd-item data-nav-id=/advanced/adapters-and-decorators><a href=/advanced/adapters-and-decorators> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Adapters and Decorators </span> </a><li class=dd-item data-nav-id=/advanced/default-adapters><a href=/advanced/default-adapters> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Built-in adapters </span> </a> <ul><li class=dd-item data-nav-id=/advanced/default-adapters/selection><a href=/advanced/default-adapters/selection> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Selection </span> </a><li class=dd-item data-nav-id=/advanced/default-adapters/array><a href=/advanced/default-adapters/array> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Array </span> </a><li class=dd-item data-nav-id=/advanced/default-adapters/ajax><a href=/advanced/default-adapters/ajax> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Ajax </span> </a><li class=dd-item data-nav-id=/advanced/default-adapters/data><a href=/advanced/default-adapters/data> <i class="fa fa-check read-icon"> </i> <span> <b> </b> SelectAdapter </span> </a><li class=dd-item data-nav-id=/advanced/default-adapters/results><a href=/advanced/default-adapters/results> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Results </span> </a><li class=dd-item data-nav-id=/advanced/default-adapters/dropdown><a href=/advanced/default-adapters/dropdown> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Dropdown </span> </a></ul></ul><li class=dd-item data-nav-id=/upgrading><a href=/upgrading> <i class="fa fa-check read-icon"> </i> <span> <b> 15. </b> Upgrading </span> </a> <ul><li class=dd-item data-nav-id=/upgrading/new-in-40><a href=/upgrading/new-in-40> <i class="fa fa-check read-icon"> </i> <span> <b> </b> What's new in 4.0 </span> </a><li class=dd-item data-nav-id=/upgrading/migrating-from-35><a href=/upgrading/migrating-from-35> <i class="fa fa-check read-icon"> </i> <span> <b> </b> Migrating from Select2 3.5 </span> </a></ul></ul><hr><a class=padding data-clear-history-toggle href=#> <i class="fa fa-fw fa-history"> </i> Clear History </a><br><section id=footer><p>By <a href=https://kevin-brown.com/> Kevin Brown </a> .<p>Select2 is licensed under <a href=https://github.com/select2/select2/blob/master/LICENSE.md> MIT </a> .<p>Docs maintained by <a href=https://alexanderweissman.com> Alexander Weissman </a> .<p>Hosted by <a title="Next Generation Internet"href=https://nextgi.com> NextGI </a> .<p>Documentation license: <a href=https://creativecommons.org/licenses/by/4.0/> CC BY 4.0 </a> .<p>Built with <a href=http://getgrav.org> Grav </a> - The Modern Flat File CMS</section></div></div></nav><section id=body><div id=overlay></div><div class="padding highlightable"><a data-sidebar-toggle href=# id=sidebar-toggle> <i class="fa fa-2x fa-bars"> </i> </a><div id=top-bar><div id=top-github-link><a class=github-link href=https://github.com/select2/select2/blob/develop/docs/pages/08.selections/docs.md> <i class="fa fa-github-square"> </i> edit this page </a></div><div id=breadcrumbs itemscope itemtype=http://data-vocabulary.org/Breadcrumb><a href=/ itemprop=url> <span itemprop=title> Getting Started </span> </a><i class="fa fa-angle-right"> </i><span itemprop=title> Selections </span></div></div><div id=body-inner><h1>Selections</h1><p><p>When an option is selected from the dropdown menu, Select2 will display the selected value in the container box. By default, it will display the <code>
       text
      </code> property of Select2's <a href=/options> internal representation of the selected option </a> .<h2>Templating</h2><p>The appearance of selected results can be customized by using the <code>
       templateSelection
      </code> configuration option. This takes a callback that transforms the selection data object into a string representation or jQuery object:<div class=s2-example><select class="js-example-templating js-states form-control"></select></div><pre data-fill-from=.js-code-example-templating></pre><script class=js-code-example-templating>function formatState (state) {
  if (!state.id) {
    return state.text;
  }

  var baseUrl = "/user/pages/images/flags";
  var $state = $(
    '<span><img class="img-flag" /> <span></span></span>'
  );

  // Use .text() instead of HTML string concatenation to avoid script injection issues
  $state.find("span").text(state.text);
  $state.find("img").attr("src", baseUrl + "/" + state.element.value.toLowerCase() + ".png");

  return $state;
};

$(".js-example-templating").select2({
  templateSelection: formatState
});</script><blockquote><blockquote><blockquote><p>You may find it helpful to use a client-side templating engine like <a href=http://handlebarsjs.com/> Handlebars </a> to define your templates.</blockquote></blockquote></blockquote><h3>Built-in escaping</h3><p>By default, strings returned by <code>
       templateSelection
      </code> are assumed to <strong> contain only text </strong> and will be passed through the <code>
       escapeMarkup
      </code> function, which strips any HTML markup.<p>If you need to render HTML with your selection template, you must wrap your rendered selection in a jQuery object. In this case, the selection will be passed <a href=https://api.jquery.com/append/> directly to <code>
        jQuery.fn.append
       </code> </a> and will be handled directly by jQuery. Any markup, such as HTML, will not be escaped and it is up to you to escape any malicious input provided by users.<blockquote><blockquote><blockquote><blockquote><p>Anything rendered as a selection is templated. This includes placeholders and pre-existing selections that are displayed, so you must ensure that your templating functions can support them.</blockquote></blockquote></blockquote></blockquote><h2>Limiting the number of selections</h2><p>Select2 multi-value select boxes can set restrictions regarding the maximum number of options that can be selected. The select below is declared with the <code>
       multiple
      </code> attribute with <code>
       maximumSelectionLength
      </code> in the select2 options.<div class=s2-example><p><select class="js-example-basic-multiple-limit js-states form-control"multiple></select></div><pre data-fill-from=.js-code-placeholder></pre><script class=js-code-placeholder>$(".js-example-basic-multiple-limit").select2({
  maximumSelectionLength: 2
});</script><h2>Clearable selections</h2><p>When set to <code>
       true
      </code> , causes a clear button ("x" icon) to appear on the select box when a value is selected. Clicking the clear button will clear the selected value, effectively resetting the select box back to its placeholder value.<pre><code>$('select').select2({
  placeholder: 'This is my placeholder',
  allowClear: true
});</code></pre><p></div></div><div id=navigation><a class="nav nav-prev"href=/dropdown> <i class="fa fa-chevron-left"> </i> </a><a class="nav nav-next"href=/tagging> <i class="fa fa-chevron-right"> </i> </a></div></section><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-57144786-2', 'auto');
  ga('send', 'pageview');</script>