Single select boxes
Select2 can take a regular select box like this...
Multi-select boxes
Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute.
Dropdown option groups
In HTML,
<option>
elements can be grouped by wrapping them with in
an
<optgroup>
element:
Disabling options
Select2 will correctly handle disabled options when
disabled
attribute is set) and from remote srouces where the object
has
disabled: true
set.
Disabling a Select2 control
Select2 will respond to the
disabled
attribute on
<select>
elements. You can also initialize Select2 with
disabled: true
to get the same effect.
Select2 With Labels
You can, and should, use a
<label>
with Select2, just like any other
<select>
element.
Container Width
The two Select2 boxes below are styled to
50%
and
75%
width respectively to support responsive design:
Themes
Select2 supports custom themes using the
theme
option so you can style Select2 to match the rest of your
application.
Ajax (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:
Loading array data
You may use the
data
configuration option to load dropdown options from a local
array.
Automatic Selection
Select2 can be configured to automatically select the
currently highlighted result when the dropdown is
btn-closed by using the
selectOnbtn-close
option:
Remain open after selection
Select2 will automatically btn-close the dropdown when an
element is selected, similar to what is done with a normal
select box. You may use the
btn-closeOnSelect
option to prevent the dropdown from closing when a result
is selected:
Dropdown placement
The
dropdownParent
option allows you to pick an alternative element for the
dropdown to be appended to:
Limiting the number of selections
Select2 multi-value select boxes can set restrictions
regarding the maximum number of options that can be
selected. The select below is declared with the
multiple
attribute with
maximumSelectionLength
in the select2 options.
Dynamic option creation
In addition to a prepopulated menu of options, Select2 can
dynamically create new options from text input by the user
in the search box. This feature is called "tagging". To
enable tagging, set the
tags
option to
true:
Tagging with multi-value select boxes
Tagging can also be used in multi-value select boxes. In
the example below, we set the
multiple="multiple"
attribute on a Select2 control that also has
tags: true
enabled:
Single select placeholders
Select2 supports displaying a placeholder value using the
placeholder
configuration option. The placeholder value will be
displayed until a selection is made.
Multi-select placeholders
For multi-selects, you must not have an
empty
<option>element:
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.
Customizing how results are matched
When users filter down the results by entering search
terms into the search box, Select2 uses an internal
"matcher" to match search terms to results. You may
customize the way that Select2 matches search terms by
specifying a callback for the
matcher
configuration option.
Matching grouped options
Only first-level objects will be passed in to the
matcher
callback. If you are working with nested data, you must
iterate through the
children
array and match them individually. This allows for more
advanced matching when working with nested objects,
allowing you to handle them however you want.
Minumum search term length
You may set a minimum search term length by using the
minimumInputLength
option:
Maximum search term length
You may limit the maximum length of search terms by using
the
maximumInputLength
option:
Programmatically add new options
New options can be added to a Select2 control
programmatically by creating a new Javascript
Option
object and appending it to the control:
Create if not exists
You can use
.find
to select the option if it already exists, and create it
otherwise:
Using jQuery selector
Selected items can also be accessed via the
:selected
jQuery selector:
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
the
dir: "rtl"
configuration option.
Destroying the Select2 control
The
destroy
method will remove the Select2 widget from the target
element. It will revert back to a standard
select
control:
Opening the dropdown
Select2 will trigger a few different events when different actions are taken using the component, allowing you to add custom hooks and perform actions.
Opening/Closing the dropdown
Select2 will trigger a few different events when different actions are taken using the component, allowing you to add custom hooks and perform actions.
Select2 methods
Select2 has several built-in methods that allow programmatic control of the component.
Select2 methods
Select2 has several built-in methods that allow programmatic control of the component.