select2: a jQuery select replacement that still earns its place

What select2 replaces, and what it leaves alone

The README describes select2 as a jQuery-based replacement for select boxes that supports searching, remote data sets and pagination of results. The interesting part is the word replacement. Select2 does not swap your native element for a div and leave you to wire values by hand. It keeps the original `<select>` in the document as the source of truth, hides it, and renders a separate search-and-dropdown interface next to it. That single design decision is why the README can say that for many platforms additional plugins are not required because select2 acts as a standard select box. Form libraries that walk the DOM for selects, server-side form posts that read selected option values, and validation that inspects `required` all keep working, because none of them were ever told a div replaced anything.

The use case list in the README is broader than search alone, and each entry maps to a native limitation rather than a nicety. Enhancing a select with search. A better multi-select interface. Loading items from JavaScript so an AJAX dataset is searchable. Nesting optgroups, which the README notes native selects restrict to one level. Tagging, meaning new items can be added on the fly. Partially loading a large remote dataset based on the search term. Paging large datasets as results scroll to the end. And templating for custom rendering of both results and selections.

The scale is worth putting in plain terms: 25,903 stars and 6,132 forks, MIT licensed, not archived, with the default branch set to `develop` and the last push on 2026-09-18. Against that, 137 open issues, which for a library this old and this widely embedded is a modest ratio. The topic list is short and honest, just `hacktoberfest`, `javascript`, `jquery` and `select2`. Nothing about a rewrite or a framework in there.

Version 4.1.0 arrived five years after its last prerelease

The release history is where you feel the project's age most clearly. Version 4.1.0-beta.1 shipped on 2020-05-02. Version 4.1.0-rc.0 shipped on 2021-01-23. The final 4.1.0 shipped on 2026-05-26. So the project spent roughly five and a half years between a release candidate and the release it was a candidate for. If you are reading the 4.1.0 notes expecting a feature list, there is not one. The final release notes are almost entirely a list of breaking changes, and reading them in order tells you what five years of accumulated feedback was judged important enough to break compatibility over.

The beta notes show the accessibility thread that runs through all three. The `autocomplete` attribute is copied over to the select2 search field so browsers stop offering stale autofill. Internal data ID generation was made more unique to prevent conflicts with numeric IDs. The selection search is resized on close so the placeholder displays properly. Internet Explorer 11 no longer steals focus of the search box while tagging. Each of these is small, and each is the kind of fix that only surfaces after a library has been in production for years.

The release candidate widened that. Significant improvements were made to make the selection area accessible, across four separate pull requests. Pasting multiple lines into the search field was allowed for tokenization. Tags are highlighted first in the results even when other options have already been selected, which is a small correctness fix with a real usability consequence: once you have five tags chosen, you can still find the next one without hunting past everything already taken. A slow memory leak caused by not clearing the cache on destroy was also fixed. For a widget that gets destroyed and recreated constantly in single-page applications, that one mattered more than its changelog line suggests.

Translations moved too. Telugu was added and Hungarian was updated for the 4.1.0 changes. Both releases also ask for financial sponsorship through GitHub Sponsors or Open Collective, and the README carries badges for both alongside jsDelivr and cdnjs.

The breaking changes that will hit an upgrade hardest

Four categories of change matter, and the first one is not really about select2.

The minimum jQuery version supported is now the latest version in the 1.x, 2.x, 3.x and 4.x series. That phrasing is deliberate: it means the latest patch of any of those four lines works, so a project on jQuery 3.7 is fine and one on jQuery 4 is fine. What is gone is support for legacy Internet Explorer, specifically versions older than IE 11. The same commit removed support for modules deprecated back in 4.0.0, which includes legacy support for `<input />` tags, the legacy `initSelection` and `query` options, and the old `select2/compat/matcher` module.

Second, a set of undocumented CSS-related options was removed: `dropdownCss`, `adaptDropdownCss`, `containerCss` and `adaptContainerCss`. These were never part of the documented API, but undocumented is not the same as unused, and if your codebase reaches for any of them you should find out from a test rather than from a production page. In the same release, `containerCssClass` was renamed to `selectionCssClass`. A rename is at least greppable, which is more than the removals give you.

Third, and this is the one that will generate the most work, the HTML and CSS for the selection area changed significantly, which the notes say impacts custom themes. New CSS classes were also added for dropdown results, to better target highlighted and selected results. If you maintain a Bootstrap or Flat UI style theme fork, this is the release to read carefully before upgrading.

Fourth, a behavioural change: the search box inside the selection area for multiple selects is now a `<textarea />` instead of an `<input />`, specifically so users can paste multiple lines, and the tab key now selects the currently highlighted option instead of only closing the dropdown. Both are improvements. The textarea in particular changes how you must write tests around that element, since query selectors written against `input` will silently find nothing.

One documentation conflict is worth flagging rather than resolving. The README browser compatibility section still lists IE 8+, Chrome 8+, Firefox 10+, Safari 3+ and Opera 10.6+. The 4.1.0 release notes state plainly that support for Internet Explorer versions older than IE 11 was removed. Both are in the repository. The release notes are the newer and more specific statement, so treat the README list as stale, and test against a modern browser target if you are upgrading.

A toolchain assembled across two eras of the web

The dependency list in `package.json` is a small archaeology of frontend development, and it explains a good deal about how the project is built:

  "main": "dist/js/select2.js",
  "style": "dist/css/select2.css",
  "files": [
    "src",
    "dist"
  ],

The build is Grunt, with `grunt-contrib-concat` to concatenate the AMD modules, `grunt-contrib-uglify` to minify, `grunt-sass` and `sass` for stylesheets, `grunt-contrib-jshint` for linting, `grunt-contrib-qunit` for browser-based unit tests, and `grunt-contrib-requirejs` to run the loader in tests. `almond` is pinned at `~0.3.3`, and almond is an AMD shim, a library whose purpose was to let AMD modules load without a RequireJS runtime. That combination is a direct fingerprint of the module system select2 grew up with, and it is why `main` points at a prebuilt `dist/js/select2.js` rather than an ES module. Consumers get a concatenated AMD bundle, and there is no modern `module` or `exports` entry point in the manifest.

Alongside that sits `.biome.json` in the repository root, plus a `.pre-commit-config.yaml`. Biome is a recent, fast linter and formatter. Having a modern tool and `grunt-contrib-jshint` and a `.jshintrc` file coexisting in one repository tells you the migration is partial and deliberate: the fast checks run on commit, the legacy checks still run in the Grunt pipeline.

The root directory also still carries `bower.json` and `component.json`. Bower and Component are both package managers that lost their ecosystem years ago, and their continued presence is a maintenance liability rather than a feature, but they are harmless if unused.

Documentation runs on a completely separate, much newer track. There is a `mkdocs.yml`, and a `pyproject.toml` that describes a Python project named `select2-docs` requiring Python 3.14 or newer, with `mkdocs`, `mkdocs-material`, `markdown-callouts`, `Pygments`, `mkdocs-git-committers-plugin-2`, `mkdocs-git-revision-date-localized-plugin` and `mkdocs-redirects` as dependencies, plus a `uv.lock`. The two npm scripts delegate to it:

  "scripts": {
    "docs:serve": "uv run mkdocs serve",
    "docs:build": "uv run mkdocs build --strict"
  }

So a JavaScript library maintains its documentation as a Python project on a 2026 toolchain, while its own test suite runs in a browser through QUnit. Both facts are true, and together they describe a project whose build tooling is legacy by inertia and whose documentation tooling is current by choice. Requiring Python 3.14 for docs is aggressive enough that it will surprise contributors on older distributions.

Integrations, themes and the i18n file convention

The README's integrations section is the fastest way to understand select2's actual adoption pattern. Third-party plugins exist for Backdrop CMS, Django, Drupal, Meteor, Ruby on Rails, Wicket, Yii 2 and AngularJS. Django alone has three listed: django-autocomplete-light, django-easy-select2 and django-select2. Wicket's entry points at a `select2-parent` module inside the Wicket core tree rather than a separate repository.

That list is a snapshot of where this kind of widget was most needed, and it is also a snapshot of a period. Rails, Django and Drupal are durable, but AngularJS is a framework most new projects would not choose today, and the list contains no React, Vue or Svelte integration at all. Google autocomplete data for the project name includes `Select2 react` as a related search, which tells you people are looking for one and not finding it in the README. The honest read is that the official integration surface stops at the pre-2015 stack, and anything newer is either a wrapper maintained elsewhere or a hand-rolled binding of the jQuery widget.

Themes follow a similar pattern. A Bootstrap 3 theme and a Bootstrap 4 theme are maintained under the select2 organisation, while the Bootstrap 5 theme is a third-party repository linked directly from the README, along with a Flat UI theme. So the answer to whether select2 works with Bootstrap 5 is yes, but the styling layer is not owned by the select2 maintainers, which matters when the 4.1.0 markup changes land and someone has to update it.

Internationalization has a fixed convention rather than a build step. Languages are plain JavaScript files loaded after the main bundle, at paths like `dist/js/i18n/it.js` and `dist/js/i18n/nl.js`, included after `dist/js/select2.js`. Contributing a language means copying `src/js/i18n/en.js`, translating it and sending a pull request. The Telugu and Hungarian work in the prereleases followed exactly that path, which is why the convention has survived intact.

The documentation itself lives in the `docs` directory of the repository and is built with MkDocs, with the rendered site hosted at select2.org. There is also a community and help page, and the README invites missing integrations to be added by opening a pull request. The project has been actively maintained, with the last push on 2026-09-18 and a final 4.1.0 release in May 2026 after years of prereleases.

What it costs to adopt, and what you get for it

The costs are concrete and worth stating without hedging.

You take on a hard dependency on jQuery, and version 4.1.0 makes it a floor as well as a ceiling: the latest release of 1.x, 2.x, 3.x or 4.x is required. In a codebase already running jQuery this is free. In a modern build where jQuery is not otherwise present, it is a genuine architectural decision, and it is the reason the React-related search phrase exists. Select2 also mutates the DOM around your select element, hiding the original and inserting a container, which means server-rendered HTML and client-side hydration both have to cooperate with it. The 4.1.0 switch to a `<textarea />` for the multi-select search is a live example of selectors written against the old markup failing quietly.

What you get is a solved problem that is genuinely hard to solve from scratch. Searchable dropdowns over large remote datasets, with paging as you scroll and tag creation from typed text, are a few hundred lines of careful work involving keyboard navigation, focus management, ARIA state and screen reader announcements. The 4.1.0 accessibility work across four pull requests exists because a maintained library accumulates that knowledge over years, and it is available to you for free.

Two operational details are worth knowing before you commit. Translations are separate files you must include yourself, so a multi-language application needs either bundling several i18n files or a deliberate choice about which locale ships. And custom themes are now on the hook for the 4.1.0 selection-area markup change, so if you fork a Bootstrap theme, budget for that update rather than discovering it as a visual regression.

There is also a licensing angle that comes out clean. The manifest declares MIT, the repository root carries `LICENSE.md`, and the README points at that file as the authoritative copy. No conflict to resolve there.

If you are evaluating this in 2026, the sequence that makes sense is straightforward: read the 4.1.0 breaking-change list against your current configuration before upgrading, decide whether the jQuery floor is acceptable for your build, and treat the README browser table as out of date compared to the release notes. If your project already runs jQuery and has a Bootstrap or plain theme, the remaining work is a test pass, not a redesign.

Editorial conclusion

select2 is one of the last genuinely popular libraries whose value proposition still rests on a dependency other projects have moved past. That is not an argument against it. It is an argument for knowing which version of jQuery you are on, whether your custom themes survive the 4.1.0 markup change, and which of the two browsers-support claims you believe. The repository is not archived, the last push was on 2026-09-18, and the maintainers shipped a long-awaited major-adjacent release in May 2026 after five years of prereleases, which reads as a project being kept alive deliberately rather than drifting. The integrations for Django, Drupal, Rails, Yii and others remain the fastest on-ramp, and the MkDocs site in the `docs` directory is where the current documentation lives. The honest summary is that adopting select2 in 2026 is a decision about jQuery as much as about select boxes, and for a jQuery codebase that decision is usually already made for you.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. select2/select2 on GitHub