File: public/asset/vendor/select2/docs/pages/10.placeholders/docs.md

title: Placeholders taxonomy:

category: docs

process:

twig: true

never_cache_twig: true

Select2 supports displaying a placeholder value using the placeholder configuration option. The placeholder value will be displayed until a selection is made.

Text placeholders

The most common situation is to use a string of text as your placeholder value.

Single select placeholders

<div class="s2-example"> <p>

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

</p> </div>

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

<pre data-fill-from="#example-placeholder-single-select"></pre>

<script type="text/javascript" id="example-placeholder-single-select" class="js-code-placeholder"> $(".js-example-placeholder-single").select2({

placeholder: "Select a state",
allowClear: true

}); </script>

>>> For single selects only, in order for the placeholder value to appear, you must have a blank <option> as the first option in your <select> control. This is because the browser tries to select the first option by default. If your first option were non-empty, the browser would display this instead of the placeholder.

Multi-select placeholders

For multi-selects, you must not have an empty <option> element:

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

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

<pre data-fill-from="#example-placeholder-multi-select"></pre>

<script type="text/javascript" id="example-placeholder-multi-select" class="js-code-placeholder"> $(".js-example-placeholder-multiple").select2({

placeholder: "Select a state"

}); </script>

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

Default selection placeholders

Alternatively, the value of the placeholder option can be a data object representing a default selection (<option>). In this case the id of the data object should match the value of the corresponding default selection.

$('select').select2({
  placeholder: {
    id: '-1', // the value of the option
    text: 'Select an option'
  }
});

This is useful, for example, when you are using a framework that creates its own placeholder option.

Using placeholders with AJAX

Select2 supports placeholders for all configurations, including AJAX. You will still need to add in the empty <option> if you are using a single select.

Customizing placeholder appearance

When using Select2 in single-selection mode, the placeholder option will be passed through the templateSelection callback if specified. You can use some additional logic in this callback to check the id property and apply an alternative transformation to your placeholder option:

$('select').select2({
  templateSelection: function (data) {
    if (data.id === '') { // adjust for custom placeholder values
      return 'Custom styled placeholder text';
    }

    return data.text;
  }
});

>>>>> When multiple selections are allowed, the placeholder will be displayed using the placeholder attribute on the search box. You can customize the display of this placeholder using CSS, as explained in the following Stack Overflow answer: Change an input's HTML5 placeholder color with CSS.

Placeholders in legacy Internet Explorer versions

Select2 uses the native placeholder attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include Placeholders.js on your page, or use the full build, in order to add placeholder attribute support to input boxes.