Modular and light-weight selection library for jQuery and Zepto.js.
I've used Select2 for a long time because I reckon it is the best and most feature-rich selection library out there.
However, time and again I've ran into its limitations. It is difficult to customize the styling, and introducing subtle tweaks to its behavior typically meant maintaining a private fork. More specifically, I wanted to make the following changes:
- Use custom templates, instead of the ones that are hard-coded in Select2. This would also open up the possibility of not loading the image sprite included with Select2, but instead use FontAwesome icons that I already use in my projects.
- Use custom loading indicators, instead of the spinner GIF included by Select2.
- I wanted to make it easier to support a use case where Select2 is used without any selection dropdown, but with the proper tokenization.
- Make Select2 work with jQuery builds without Sizzle for better performance. Patches for this have been accepted in Select2, but unfortunately it's a moving target causing repeated breakage. Also, once Sizzle is no longer required, it becomes much easier to support Zepto.js.
- Personally, I preferred a more modern codebase to work with, rather than the huge monolithic library that is Select2. This also includes proper documentation of the code as well as good test coverage. At this point also support for any IE version older than 10 can be dropped.
Having said that, if you're a user of Select2 and don't recognize yourself in any of these issues, I advise you to keep using Select2. It's feature-rich and actively supported, so don't fix what ain't broken ;)
Selectivity only relies on jQuery or Zepto.js being loaded on the page to work.
In addition, the default templates assume that you have included FontAwesome in your page to display the icons.
Copy selectivity-full.js and selectivity-full.css from the dist/ directory into your project.
Then put the following in your HTML head:
<head>
...
<link href="font-awesome.css" rel="stylesheet">
<link href="selectivity-full.css" rel="stylesheet">
...
<script src="jquery.js"></script>
<script src="selectivity-full.js"></script>
...
</head>
Verify the paths are correct for your particular project. The important thing is that jQuery (or Zepto.js) should be loaded before including Selectivity.
Make sure Bower is installed, then run:
$ bower install selectivity
Include as a component(1) dependency.
In your component.json:
{
"dependencies": {
...
"arendjr/selectivity": "^2.1.0"
...
}
}
And in your code:
var $ = require('jquery');
require('selectivity');
Detailed information for selectivity-rails, including
Installation and usage are
provided in the gem's repository.
- Chrome
- Firefox
- Internet Explorer 10+
- Safari 6+
Note that while Internet Explorer versions older than 10 are not supported, you might be able to get them to work, possibly with the use of some polyfills. Reports of success or patches to create a "legacy" build would be welcomed.
See the Selectivity homepage: https://arendjr.github.io/selectivity/
Selectivity is built modularly and uses Gulp as a build system to build its distributable files. To install the necessary dependencies, please run:
$ npm install -g gulp
$ npm install
Then you can generate new distributable files from the sources, using:
$ npm run build
If you want to create your own Selectivity library that contains just the modules you need, you can use the following command:
$ gulp --modules=<comma-separated-module-list>
The following modules are available:
| Module | Description |
|---|---|
| ajax | Convenience module for performing AJAX requests. All options passed into the ajax object are provided by this module. |
| async | Blocks the query function from calling its callback functions if another query has been issued since. This prevents out-of-order replies from remote sources to display incorrect results. This module is only needed if you use the query function and call its callbacks asynchronously. |
| base | The Selectivity base module which is pulled in automatically into every build. |
| diacritics | Diacritics support. This will make sure that "Łódź" will match when the user searches for "Lodz", for example. However, if you always query a server when searching for results, you may want to solve matching of diacritics server-side, in which case this module can be ommitted. |
| dropdown | Module that implements the dropdown. You will most likely want to include this, unless you only want to use Selectivity without any dropdown or you provide a completely custom implementation instead. |
| Implements the 'Email' input type. This is a special case of the 'Multiple' input type with no dropdown and a specialized tokenizer for recognizing email addresses (including pasted content from address books). | |
| keyboard | Provides keyboard support for navigating through the dropdown. If you don't use a dropdown, or are only targeting mobile, you may want to leave this module out. |
| locale | Localizable content pulled in by the default templates. You may or may not decide to use these with your own templates. Also used for localizable messages by the ajax module. |
| multiple | Implements the 'Multiple' input type. If you only want to use Selectivity with single values, you can leave this out. |
| single | Implements the 'Single' input type. If you only want to use Selectivity with multiple values, you can leave this out. |
| submenu | Extends the default dropdown so that multiple levels of submenus can be created. |
| templates | Default templates to use with Selectivity. If you provide your own templates, you may want to skip this. |
| tokenizer | Default tokenizer implementation. This module adds support for the tokenSeparators option which is used by the default tokenizer. Support for tokenizers themselves is already included in the "multiple" module, so you can omit this module if you don't want to use any tokenizers or want to specify your own tokenizer. |
| traditional | This module allows you to convert an HTML5 <select> form element into a Selectivity instance. The items will be initialized from the <option> and <optgroup> elements. |
Note that the build system automatically resolves dependencies between modules, so you never need to explicitly specify that you want to include the base module, as it will be pulled in by others.
Example:
$ gulp --modules=multiple,dropdown
This will create a custom build with support for selecting multiple values and a dropdown. The build
will be saved in dist/selectivity-custom.js. There will be no diacritics support, you will have to
provide your own templates with their localizable content, and you cannot use this build for
creating a single-select input.
Note that because Selectivity uses Browserify internally, the build will contain various require()
calls, which may sometimes interfere with build systems that scan for those calls. If this gives
problems for you, you can pass the --derequire parameter to rename those calls. Of course, if
you're using Browserify in your own project you may even decide to skip the whole build process and
just copy the relevant modules from the src/ directory straight into your project.
To display any other options available for custom builds, run gulp --help.
While developing, you can start a development server like this:
$ gulp dev [--modules=<comma-separated-module-list>] [--source-map]
You may want to pass the --source-map parameter to generate a source map for debugging. The file
demos/custom.html is set up to work with custom builds, which you can also use for development.
Unit tests are available and can be ran using the following command:
$ gulp unit-tests
Before you decide to migrate from Select2 to Selectivity, you should consider that not every feature supported by Select2 is supported by Selectivity. So check beforehand whether Selectivity actually meets your requirements.
The following is an (incomplete) list of features which Selectivity currently lacks:
- Reordering of selected items. Select2 allows reordering of selected items, for example through drag 'n drop. Selectivity doesn't and there are curently no plans to implement this.
- Options. Selectivity lacks some miscellaneous options supported by Select2. Notable omissions are
selectOnBlurandmaximumSelectionSize, among others. - Events. Select2 currently emits more events than Selectivity does. Notable omissions are 'select2-clearing', 'select2-focus' and 'select2-blur' among others.
- Select2 has explicit support for tags through the
tagsoption. With Selectivity, tagging is also supported, but works through the regularitemsoption. - Formatting functions. Select2 allows you to specify a wide range of
format*()functions in the options. With Selectivity, instead of passing various formatting functions, you can customize the templates, both globally and per instance.
- If you have customized the CSS you use with Select2, you will have to take into account that you may need to customize it again for Selectivity as the templates are very different.
- Some properties are named differently, even though they have very similar meaning. Examples:
createSearchChoiceis nowcreateTokenItem.- The
choiceparameter to events is now calleditem.
Patches for bugfixes are always welcome. Please accompany pull requests for bugfixes with a test case that is fixed by the PR.
If you want to implement a new feature, I advise to open an issue first in the GitHub issue tracker so we can discuss its merits.
In the absence of a formal style guide, please take the following into consideration:
- Use four spaces, no tabs.
- Prefer single quotes.
- No lines longer than 100 characters.
Also make sure you don't check-in any ESLint violations.
In order to validate your code before pushing, please run the following script:
$ tools/install-git-hooks.sh
This will install a Git pre-push hook that will run Eslint and all unit tests before pushing.