Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

select2

select21.9mMIT4.1.0-rc.0TypeScript support: definitely-typed

Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results.

select, autocomplete, typeahead, dropdown, multiselect, tag, tagging

readme

Select2

Build Status Financial Contributors on Open Collective jsdelivr cdnjs

Select2 is a jQuery-based replacement for select boxes. It supports searching, remote data sets, and pagination of results.

To get started, checkout examples and documentation at https://select2.org/

Use cases

  • Enhancing native selects with search.
  • Enhancing native selects with a better multi-select interface.
  • Loading data from JavaScript: easily load items via AJAX and have them searchable.
  • Nesting optgroups: native selects only support one level of nesting. Select2 does not have this restriction.
  • Tagging: ability to add new items on the fly.
  • Working with large, remote datasets: ability to partially load a dataset based on the search term.
  • Paging of large datasets: easy support for loading more pages when the results are scrolled to the end.
  • Templating: support for custom rendering of results and selections.

Browser compatibility

  • IE 8+
  • Chrome 8+
  • Firefox 10+
  • Safari 3+
  • Opera 10.6+

Usage

You can source Select2 directly from a CDN like jsDelivr or cdnjs, download it from this GitHub repo, or use one of the integrations below.

Integrations

Third party developers have created plugins for platforms which allow Select2 to be integrated more natively and quickly. For many platforms, additional plugins are not required because Select2 acts as a standard <select> box.

Plugins

Themes

Missing an integration? Modify this README and make a pull request back here to Select2 on GitHub.

Internationalization (i18n)

Select2 supports multiple languages by simply including the right language JS file (dist/js/i18n/it.js, dist/js/i18n/nl.js, etc.) after dist/js/select2.js.

Missing a language? Just copy src/js/select2/i18n/en.js, translate it, and make a pull request back to Select2 here on GitHub.

Documentation

The documentation for Select2 is available online at the documentation website and is located within the docs directory of this repository.

Community

You can find out about the different ways to get in touch with the Select2 community at the Select2 community page.

The license is available within the repository in the LICENSE file.

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

changelog

Change Log

4.1.0 (unreleased)

Breaking changes

  • The minimum jQuery version supported is the latest version in the 1.x, 2.x, and 3.x series (#5525, #5955)
  • Removed support for legacy Internet Explorer (versions older than IE 11) (#5834)
  • Removed modules deprecated in 4.0.0 (#5815)
    • Removed legacy support for <input /> tags
    • Removed legacy support for initSelection
    • Removed legacy support for query
    • Removed old select2/compat/matcher module
  • Removed undocumented CSS-related options (#5815)
    • Removed dropdownCss option
    • Removed adaptDropdownCss option
    • Removed containerCss option
    • Removed adaptContainerCss option
  • The containerCssClass option has been renamed to selectionCssClass (#5815, #5847)
  • Significant changes to the HTML/CSS for the selection area impacting custom themes (#5842)
  • New CSS classes for the dropdown results to better target highlighted / selected results (#5841)
  • The search box in the selection area for multiple selects has been changed from an <input /> to a <textarea> to support pasting multiple lines (#5806)
  • Change tab key to select the currently highlighted option instead of just closing (#5759)
  • Tags will be highlighted first in the results even if other options have been selected (#5812)

New features / improvements

  • dropdownCssClass and selectionCssClass are now available in all builds of Select2 (#5815)
  • Calls to get the currently selected options are now considerably faster on large datasets (#5775)
  • Selected results in the dropdown should now be properly announced to screen readers (#5841)
  • Significant improvements were made to make the selection area accessible (#5824, #5842, #5916, #5942, #5973)
  • Allow pasting multiple lines into the search field for tokenization (#5806)

Bug fixes

  • Resize the selection search on close to properly display the placeholder (#5766)
  • Change internal data ID generation to be more unique and prevent conflicts with numeric IDs (#5840)
  • Internet Explorer 11 no longer steals focus of search box while tagging (#5842)
  • Fix slow memory leak caused by not clearing cache on destroy (#5965)

Translations

  • Add Esperanto translation (eo) (#5823)
  • Add Punjabi translations (pa) (#5831)
  • Add Telugu translations (te) (#5881)
  • Updated Hungarian translations (hu) for 4.1.0 changes (#5970)

Miscellaneous

  • The amdLanguageBase option no longer has an effect because the full build does not include any dynamically loaded modules (#5815)

4.0.13

New features / improvements

  • Trigger input event before change events (#4649)
  • Feed back the keypress code that was responsible for the 'close' event (#5513)
  • Only trigger selection:update once on DOM change events (#5734)

Bug fixes

  • Prevent opening of disabled elements (#5751)

Documentation

  • Fix "edit this page" links in docs (#5689)

Miscellaneous

  • Registered Select2 on Open Collective (#5700, #5721, #5741)

4.0.12

Bug fixes

  • Fixes incorrect offset when using the Shadow DOM and styling the <html> element (#5682)

Miscellaneous

  • Replace cdnjs with jsDelivr in the documentation (#5687)
  • Fix incorrect provider for the automated NPM deployment (#5686)

4.0.11

Bug fixes

  • Fixes jQuery migrate error when getting offset when dropdownParent not in document (#5584)

Miscellaneous

  • Enable GitHub actions for CI (#5591)
  • Documentation has been moved into and is deployed from the code repository (#5638)
  • Remove Travis CI integration (#5665)

4.0.10

New features / improvements

  • Support passing in a selector for dropdownParent option (#5622)

Bug fixes

  • Fix bug where dropdowns pointing upwards were incorrectly positioned (#5621)

4.0.9

New features / improvements

  • Mirror disabled state through aria-disabled on selection (#5579)
  • Select2 now clears the internal ID when it is destroyed (#5587)
  • Set the main ARIA 1.1 roles and properties for comboboxes (#5582)
  • The language option now has a clearly defined fallback chain (#5602)

Bug fixes

  • Do not propagate click when search box is not empty (#5580)
  • Fix maximumSelectionLength being ignored by closeOnSelect (#5581)
  • Fix generated options not receiving result IDs (#5586)
  • Remove selection title attribute if text is empty (#5589)
  • Reposition dropdown whenever items are selected (#5590)
  • Fix dropdown positioning when displayed above with messages (#5592)
  • Fix search box expanding width of container (#5595)
  • allowClear no longer shifts selections to a new line (#5603)

Translations

  • Fix error in German translations (#5604)

Miscellaneous

  • Updated development grunt version so it no longer shows as vulnerable (#5597)
  • Remove unused variables (#5554)

4.0.8

New features / improvements

  • Test against and fix compatibility with jQuery 3.4.1 (#5531)
  • Results respect disabled state of <option> (#5560)
  • Add computedstyle option for calculating the width (#5559)

Bug fixes

  • Fix tag creation being broken in 4.0.7 (#5558)
  • Fix infinite scroll when the scrollbar is not visible (#5575)
  • Revert change to focusing behaviour in 4.0.6 (#5576)

Translations

  • Fix wording in French translations (#5521)

Miscellaneous

  • Update grunt-contrib-qunit to latest version (#5530)
  • Removed unused .select2-selection__placeholder CSS definitions for multiple selects (#5508)
  • Remove deprecated jQuery shorthand (#5564)

4.0.7

New features/improvements

  • Do not close on select if Ctrl or Meta (Cmd) keys being held (#5222)

Bug fixes

  • Fixed issue where single select boxes would automatically reopen when they were closed (#5490, #5492)

Miscellaneous

  • Move almost and jquery-mousewheel to devDependencies (#5489)

4.0.6

New features/improvements

  • Add style property to package.json (#5019)
  • Implement clear and clearing events (#5058)
  • Add scrollAfterSelect option (#5150)
  • Add missing diacritics (#4118, #4337, #5464)

Bug fixes

  • Fix up arrow error when there are no options in dropdown (#5127)
  • Add ; before beginning of factory wrapper (#5089)
  • Fix IE11 issue with select losing focus after selecting an item (#4860)
  • Clear tooltip from select2-selection__rendered when selection is cleared (#4640, #4746)
  • Fix keyboard not closing when closing dropdown on iOS 10 (#4680)
  • User-defined types not normalized properly when passed in as data (#4632)
  • Perform deep merge for Defaults.set() (#4364)
  • Fix "the results could not be loaded" displaying during AJAX request (#4356)
  • Cache objects in Utils.__cache instead of using $.data (#4346, #5486)
  • Removing the double event binding registration of selection:update (#4306)

Accessibility

  • Improve .select2-hidden-accessible (#4908)
  • Add role and aria-readonly attributes to single selection dropdown value (#4881)

Translations

  • Add Turkmen translations (tk) (#5125)
  • Fix error in French translations (#5122)
  • Add Albanian translation (sq) (#5199)
  • Add Georgian translation (ka) (#5179)
  • Add Nepali translation (ne) (#5295)
  • Add Bangla translation (bn) (#5248)
  • Add removeAllItems translation for clear "x" title (#5291)
  • Fix wording in Vietnamese translations (#5387)
  • Fix error in Russian translation (#5401)

Miscellaneous

  • Remove duplicate CSS selector in classic theme (#5115)

4.0.5

Bug fixes

  • Replace autocapitalize=off with autocapitalize=none (#4994)

Translations

  • Vietnamese: remove an unnecessary quote mark (#5059)
  • Czech: Add missing commas and periods (#5052)
  • Spanish: Update the 'errorLoading' message (#5032)
  • Fix typo in Romanian (#5005)
  • Improve French translation (#4988)
  • Add Pashto translation (ps) (#4960)
  • Add translations for lower and upper Sorbian (dsb and hsb) (#4949)
  • Updates to Slovak (#4915)
  • Fixed Norwegian inputTooShort message (#4817, 4896)
  • Add Afrikaans translation (af) (#4850)
  • Add Bosnian translation (bs) (#4504)

4.0.4

New features / Improvements

Bug fixes

Documentation

Translations

4.0.3

This is the third bugfix release of Select2 4.0.0. It builds upon the second bugfix release and fixes many common issues.

New features / Improvements

Bug fixes

Documentation

Translations

4.0.2

This is the second bugfix release of Select2 4.0.0. It builds upon the first release candidate of Select2 4.0.2 with some minor improvements.

New features / Improvements

Bug fixes

Documentation

Translations

4.0.1

This is the first bugfix release of Select2 4.0.0. It builds upon the first release candidate of Select2 4.0.1 with some minor improvements.

New features / improvements

Bug fixes

Design

Documentation

Translations

4.0.0

This builds upon the second release candidate, so review all previous release notes before upgrading from previous versions of Select2.

Supported environments

  • jQuery 1.7.2+
  • Modern browsers (Chrome, Firefox, Safari)
  • Internet Explorer 8+

New features

Breaking changes

Options

  • The default value of the width option has been changed from style to resolve.
  • The copy value for the width option has been renamed to style.
Renamed
  • formatSelection -> templateSelection
  • formatResult -> templateResult
  • sortResults -> sorter
  • createSearchChoice -> createTag
  • selectOnBlur -> selectOnClose
  • ajax.jsonpCallback -> ajax.jsonp
  • ajax.results -> ajax.processResults
  • tags: [array,of,data] -> data: [array,of,data], tags: true
  • placeholderOption has been replaced by placeholder.id (placeholder -> placeholder.text)
Internationalization
  • formatNoMatches -> language.noMatches
  • formatSearching -> language.searching
  • formatInputTooShort -> language.inputTooShort
  • formatInputTooLong -> language.inputTooLong
  • formatAjaxError -> language.errorLoading
  • formatLoading -> language.loadingMore
  • formatSelectionTooBig -> language.maximumSelected
Deprecated/Removed
  • initSelection - This is no longer needed with <select> tags. Limited backwards compatibility in the full build.
  • id - Data objects should now always have id and text attributes that are strings, use $.map when migrating
  • query - Use a custom data adapter instead. Limited backwards compatibility in the full build.
  • ajax.params - All parameters passed to ajax will be passed to the AJAX data transport function

Methods

Renamed
  • .select2("val", [value]) -> .val([value])
  • .select2("enable", !disabled) -> .prop("disabled", disabled)
Removed
  • .select2("onSortStart") and .select2("onSortEnd") - A custom selection adapter should be created instead
  • .select2("data", data) - Create the <option> tags for the objects that you would like to set, and set the .val to select them
  • .select2("readonly") - There is no way to make a <select> element read-only, disable it instead

Events

New
  • select2:closing is triggered before the dropdown is closed
  • select2:select is triggered when an option is selected
Renamed
  • select2-close is now select2:close
  • select2-open is now select2:open
  • select2-opening is now select2:opening
  • select2-selecting is now select2:selecting
  • select2-removed is now select2:unselect
  • select2-removing is now select2:unselecting
Removed
  • select2-clearing has been removed in favor of select2:unselecting
  • select2-highlight
  • select2-loaded
  • select2-focus - Use the native focus event instead
  • select2-blur - Use the native blur event instead
  • All extra properties from the change event were removed
    • val can be retrieved with $element.val() instead
    • added can be retrieved by listening to select2:select
    • removed can be retrieved by listening to select2:unselect