placeholder.html 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384
  1. <section>
  2. <h2 id="placeholder">
  3. How can I have Select2 display a placeholder?
  4. </h2>
  5. <p>
  6. Select2 supports displaying a placeholder by default using the <code>placeholder</code> option. This can be either a data object matching the placeholder option, or a string to display as the placeholder if you are using a blank placeholder option.
  7. </p>
  8. {% highlight js linenos %}
  9. $('select').select2({
  10. placeholder: 'Select an option'
  11. });
  12. {% endhighlight %}
  13. <h3>
  14. My first option is being displayed instead of my placeholder
  15. </h3>
  16. <p>
  17. This usually means that you do not have a blank <code>&lt;option&gt;&lt/option&gt;</code> as the first option in your <code>&lt;select&gt;</code>.
  18. </p>
  19. <p>
  20. Note that this does not apply to multiple selects, as the browser does not select the first option by default when multiple selections can be made.
  21. </p>
  22. <h3>
  23. I am using AJAX, can I still show a placeholder?
  24. </h3>
  25. <p>
  26. Yes, Select2 supports placeholders for all configurations. You will still need to add in the placeholder option if you are using a single select.
  27. </p>
  28. <h3>
  29. Can I use an option without a blank value as my placeholder?
  30. </h3>
  31. <p>
  32. The <code>placeholder</code> option allows you to pass in a data object instead of just a string if you need more flexibility. The <code>id</code> of the data object should match the <code>value</code> of the placeholder option.
  33. </p>
  34. {% highlight js linenos %}
  35. $('select').select2({
  36. placeholder: {
  37. id: '-1', // the value of the option
  38. text: 'Select an option'
  39. }
  40. });
  41. {% endhighlight %}
  42. <h3>
  43. Can I change how the placeholder looks?
  44. </h3>
  45. <p>
  46. When using Select2 <strong>when only a single selection can be made</strong>, the placeholder option will be passed through the standard templating methods, including the <code>templateSelection</code> option, so you are able to change how it is displayed.
  47. </p>
  48. {% highlight js linenos %}
  49. $('select').select2({
  50. templateResult: function (data) {
  51. if (data.id === '') { // adjust for custom placeholder values
  52. return 'Custom styled placeholder text';
  53. }
  54. return data.text;
  55. }
  56. });
  57. {% endhighlight %}
  58. <p>
  59. <strong>When multiple selections are allowed</strong>, the placeholder will be displayed using the <code>placeholder</code> attribute on the search box. You can cusotmize the display of this placholder using CSS, as explained in the following Stack Overflow answer: <a href="http://stackoverflow.com/q/2610497/359284">Change an input's HTML5 placeholder color with CSS</a>
  60. </p>
  61. <h3>
  62. My placeholders aren&apos;t being displayed in Internet Explorer
  63. </h3>
  64. <p>
  65. Select2 uses the native <code>placeholder</code> attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include <a href="https://github.com/jamesallardice/Placeholders.js">Placeholders.js</a> on your page, or use the full build, in order to add <code>placeholder</code> attribute support to input boxes.
  66. </p>
  67. </section>