82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
|
---
|
||
|
|
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.
|
||
|
|
|
||
|
|
**In order for a string 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. Note that this issue does not apply to multiple selects.
|
||
|
|
|
||
|
|
<div class="s2-example">
|
||
|
|
<p>
|
||
|
|
<select class="js-example-placeholder-single js-states form-control">
|
||
|
|
<option></option>
|
||
|
|
</select>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<select class="js-example-placeholder-multiple 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-placeholder-single").select2({
|
||
|
|
placeholder: "Select a state",
|
||
|
|
allowClear: true
|
||
|
|
});
|
||
|
|
|
||
|
|
$(".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 <a href="https://github.com/jamesallardice/Placeholders.js">the Placeholders.js polyfill</a>.
|
||
|
|
|
||
|
|
## 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'
|
||
|
|
}
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## 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](http://stackoverflow.com/q/2610497/359284).
|
||
|
|
|
||
|
|
## 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](https://github.com/jamesallardice/Placeholders.js) on your page, or use the full build, in order to add `placeholder` attribute support to input boxes.
|