File: public/asset/vendor/select2/docs/pages/08.selections/docs.md

title: Selections taxonomy:

category: docs

process:

twig: true

never_cache_twig: true

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 text property of Select2's internal representation of the selected option.

Templating

The appearance of selected results can be customized by using the templateSelection 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 type="text/javascript" class="js-code-example-templating">

function formatState (state) { if (!state.id) {

return state.text;

}

var baseUrl = "{{ url('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>

>>> You may find it helpful to use a client-side templating engine like Handlebars to define your templates.

Built-in escaping

By default, strings returned by templateSelection are assumed to contain only text and will be passed through the escapeMarkup function, which strips any HTML markup.

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 directly to jQuery.fn.append 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.

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

Limiting the number of selections

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 multiple attribute with maximumSelectionLength in the select2 options.

<div class="s2-example">

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

</div>

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

<script type="text/javascript" class="js-code-placeholder">

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

</script>

Clearable selections

When set to true, 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.

$('select').select2({
  placeholder: 'This is my placeholder',
  allowClear: true
});