select2/pages/07.dropdown/docs.md

title	taxonomy	process	never_cache_twig
Dropdown	category docs	twig true	true

This chapter covers the appearance and behavior of the list of results in the dropdown menu.

Templating

By default, Select2 will display the text property of each data object within the list of results. The appearance of search results in the dropdown can be customized by using the templateResult option:

The templateResult function should return a string containing the text to be displayed, or an object (such as a jQuery object) that contains the data that should be displayed. It can also return null, which will prevent the option from being displayed in the results list.

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 templateResult 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 result template, you must wrap your rendered result in a jQuery object. In this case, the result 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 in the results is templated. This includes results such as the "Searching..." and "Loading more..." text which will periodically be displayed, which allows you to add more advanced formatting to these automatically generated options. You must ensure that your templating functions can support them.

Automatic selection

Select2 can be configured to automatically select the currently highlighted result when the dropdown is closed by using the selectOnClose option:

$('#mySelect2').select2({
  selectOnClose: true
});

Forcing the dropdown to remain open after selection

Select2 will automatically close the dropdown when an element is selected, similar to what is done with a normal select box. You may use the closeOnSelect option to prevent the dropdown from closing when a result is selected:

$('#mySelect2').select2({
  closeOnSelect: false
});

Note that this option is only applicable to multi-select controls.

If the CloseOnSelect decorator is not used (or closeOnSelect is set to false), the dropdown will not automatically close when a result is selected. The dropdown will also never close if the ctrl key is held down when the result is selected.

Dropdown placement

Attention Harvest Chosen migrators! If you are migrating to Select2 from Chosen, this option will cause Select2 to position the dropdown in a similar way.

By default, Select2 will attach the dropdown to the end of the body and will absolutely position it to appear above or below the selection container.

Select2 will display the dropdown above the container if there is not enough space below the container, but there is enough space above it.

The dropdownParent option allows you to pick an alternative element for the dropdown to be appended to:

$('#mySelect2').select2({
  dropdownParent: $('#myModal')
});

This is useful when attempting to render Select2 correctly inside of modals and other small containers. If you're having trouble using the search box inside a Bootstrap modal, for example, trying setting the dropdownParent option to the modal element.

If you run into positioning issues while using the default body attachment, you may find it helpful to use your browser console to inspect the values of:

• document.body.style.position
• $(document.body).offset()

See this issue.

dropdownParent will cause DOM events to be raised outside of the standard Select2 DOM container. This can cause issues with third-party components such as modals.