The basics
Select2 can take a regular select box like this...
and turn it into this...
Multiple select boxes
Select2 also supports multi-value select boxes. The select below is declared with the multiple
attribute.
Placeholders
A placeholder value can be defined and will be displayed until a
selection is made. 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.
Other data sources
Loading array data
Select2 provides a way to load the data from a local array. You can provide initial selections with array data by providing the option tag for the selected values, similar to how it would be done for a standard select.
Loading remote data
Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API.
When using Select2 with remote data, the HTML required for the
select
is the same as any other Select2. If you need to
provide default selections, you just need to include an
option
for each selection that contains the value and text
that should be displayed.
You can configure how Select2 searches for remote data using the
ajax
option. More information on the individual options
that Select2 handles can be found in the
options documentation for ajax
.
Select2 will pass any options in the ajax
object to
jQuery's $.ajax
function, or the transport
function you specify.
Disabled mode
Select2 will response the disabled
attribute on
<select>
elements. You can also initialize Select2
with disabled: true
to get the same effect.
Disabled results
Select2 will correctly handled disabled results, both with data coming
from a standard select (when the disabled
attribute is set)
and from remote sources, where the object has
disabled: true
set.
Limiting the number of selections
Select2 multi-value select boxes can set restrictions regarding the
maximum number of options selected. The select below is declared with
the multiple
attribute with maxSelectionLength
in the select2 options.
Hiding the search box
Select2 allows you to hide the search box depending on the number of
options which are displayed. In this example, we use the value
Infinity
to tell Select2 to never display the search box.
Programmatic control
Events
Select2 will trigger some events on the original select element, allowing you to integrate it with other components. You can find more information on events on the options page.
change
is fired whenever an option is selected or removed.
select2:open
is fired whenever the dropdown is opened.
select2:opening
is fired before this and can be prevented.
select2:close
is fired whenever the dropdown is closed.
select2:closing
is fired before this and can be prevented.
select2:select
is fired whenever a result is selected.
select2:selecting
is fired before this and can be prevented.
select2:unselect
is fired whenever a result is unselected.
select2:unselecting
is fired before this and can be prevented.
Programmatic access
Select2 supports methods that allow programmatic control of the component.
Tagging support
Select2 can be used to quickly set up fields used for tagging.
Note that when tagging is enabled the user can select from pre-existing options or create a new tag by picking the first choice, which is what the user has typed into the search box so far.
Automatic tokenization
Select2 supports ability to add choices automatically as the user is typing into the search field. Try typing in the search field below and entering a space or a comma.
The separators that should be used when tokenizing can be specified using the tokenSeparators options.
Custom matcher
Unlike other dropdowns on this page, this one matches options only if the term appears in the beginning of the string as opposed to anywhere:
This custom matcher uses a compatibility module that is only bundled in the full version of Select2. You also have the option of using a more complex matcher.
Localization, RTL and diacritics support
Multiple languages
Select2 supports displaying the messages in different languages, as well as providing your own custom messages that can be displayed.
The language does not have to be defined when Select2 is being
initialized, but instead can be defined in the [lang]
attribute of any parent elements as [lang="es"]
.
RTL support
Select2 will work on RTL websites if the dir
attribute is
set on the <select>
or any parents of it. You can also
initialize Select2 with dir: "rtl"
set.
Diacritics support
Select2's default matcher will ignore diacritics, making it easier for users to filter results in international selects. Type "aero" into the select below.
Themes, templating and responsive design
Theme support
Select2 supports custom themes using the theme option so you can style Select2 to match the rest of your application.
These are using the classic
theme, which matches the old
look of Select2.
Templating
Various display options of the Select2 component can be changed:
You can access the <option>
element
(or <optgroup>
) and any attributes on those elements
using .element
.
Templating is primarily controlled by the
templateResult
and templateSelection
options.
Responsive design - Percent width
Select2's width can be set to a percentage of its parent to support responsive design. The two Select2 boxes below are styled to 50% and 75% width respectively.
style
declaration into the tag.