{"id":13493738,"url":"https://github.com/arendjr/selectivity","last_synced_at":"2025-10-22T17:24:56.984Z","repository":{"id":25169401,"uuid":"28592439","full_name":"arendjr/selectivity","owner":"arendjr","description":"Modular and light-weight selection library","archived":true,"fork":false,"pushed_at":"2020-03-12T10:26:24.000Z","size":6705,"stargazers_count":1101,"open_issues_count":41,"forks_count":108,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-03-01T02:51:13.269Z","etag":null,"topics":["component","form","javascript","jquery-plugin","react","select","ui"],"latest_commit_sha":null,"homepage":"https://arendjr.github.io/selectivity/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arendjr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-29T13:02:36.000Z","updated_at":"2024-12-18T01:49:35.000Z","dependencies_parsed_at":"2022-08-30T20:00:53.465Z","dependency_job_id":null,"html_url":"https://github.com/arendjr/selectivity","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arendjr%2Fselectivity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arendjr%2Fselectivity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arendjr%2Fselectivity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arendjr%2Fselectivity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arendjr","download_url":"https://codeload.github.com/arendjr/selectivity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246030681,"owners_count":20712418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","form","javascript","jquery-plugin","react","select","ui"],"created_at":"2024-07-31T19:01:18.330Z","updated_at":"2025-10-22T17:24:51.621Z","avatar_url":"https://github.com/arendjr.png","language":"JavaScript","readme":"# Selectivity.js\n\nModular and light-weight selection library.\n\n**Deprecation notice:** At [Speakap](https://speakap.com/), we are migrating to a more responsive\ncomponent library. As such, we will be migrating away from Selectivity, and we will no longer be\nmaintaining this library. If you are interested in taking over ownership, please\n[file an issue](https://github.com/arendjr/selectivity/issues). Thanks for all the support!\n\n## Setup\n\n### Dependencies\n\nSelectivity doesn't require any external libraries to be loaded on your page, but it does have some\noptional dependencies:\n\n-   There's a React build that provides the official Selectivity React API. If you wish to use this,\n    [React](https://facebook.github.io/react/) should be loaded on your page.\n-   There's a jQuery build that provides the official Selectivity jQuery API. If you wish to use\n    this, either [jQuery](http://jquery.com/) or [Zepto.js](http://zeptojs.com/) should be loaded on\n    your page.\n-   The default templates assume that you have included\n    [FontAwesome](http://fortawesome.github.io/Font-Awesome/) in your page to display the icons. If\n    you do not want this, please specify custom templates.\n\n### Manual\n\n**Warning:** Do you use Browserify or Webpack? Please use Yarn or NPM as described below.\n\nDownload and unpack the latest release from the project website:\nhttps://arendjr.github.io/selectivity/\n\nCopy the JavaScript and CSS file for your desired build from the archive into your project. See the\nfollowing table to see which files you need:\n\n| Build                     | JavaScript file           | CSS file                   |\n| ------------------------- | ------------------------- | -------------------------- |\n| jQuery (development)      | selectivity-jquery.js     | selectivity-jquery.css     |\n| jQuery (production)       | selectivity-jquery.min.js | selectivity-jquery.min.css |\n| React (development)       | selectivity-react.js      | selectivity-react.css      |\n| React (production)        | selectivity-react.min.js  | selectivity-react.min.css  |\n| _VanillaJS_ (development) | selectivity.js            | selectivity.css            |\n| _VanillaJS_ (production)  | selectivity.min.js        | selectivity.min.css        |\n\nReference the files from your HTML page like this:\n\n```html\n\u003chead\u003e\n    \u003c!-- ... --\u003e\n    \u003clink href=\"font-awesome.css\" rel=\"stylesheet\" /\u003e\n    \u003clink href=\"selectivity.css\" rel=\"stylesheet\" /\u003e\n    \u003c!-- ... --\u003e\n    \u003cscript src=\"jquery-or-react-or-zepto.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"selectivity.js\"\u003e\u003c/script\u003e\n    \u003c!-- ... --\u003e\n\u003c/head\u003e\n```\n\nNote the first line includes FontAwesome which is required for the default icons. This line is\noptional if you use custom templates.\n\nThe second line should reference the CSS file from the bundle you chose to use.\n\nThe third line should reference jQuery, React or Zepto.js as appropriate. This line is optional if\nyou use the VanillaJS bundle. _Note: If you want to use the React templates plugin, don't forget to\nalso include `react-dom.js`._\n\nFinally, the last line should reference the JavaScript file from the bundle you chose to use.\n\nYou are now ready to start using Selectivity as described on the Selectivity homepage:\nhttps://arendjr.github.io/selectivity/\n\n### Using Yarn or NPM\n\nUse one of the following commands, depending on whether you have Yarn or NPM installed:\n\n    $ yarn add selectivity\n\n    $ npm install --save selectivity\n\nNote you will need to include the CSS yourself. You can find it in\n`node_modules/selectivity/selectivity.css`.\n\n#### Which module do I require?\n\nYou can `require()` Selectivity as follows:\n\n```js\nconst Selectivity = require(\"selectivity\");\n```\n\nBut, this will only expose the main Selectivity object and will load none of the plugins, nor enable\nany of the specialized APIs. You could say what you're getting is the core of the VanillaJS API.\n\nIf however, you just want to use the jQuery API with all the relevant plugins loaded, you can do\nthis:\n\n```js\nrequire(\"selectivity/jquery\");\n```\n\nAfter this you can call the jQuery API as you would expect:\n\n```js\n$(\"...\").selectivity(/*...*/);\n```\n\nSimilarly, if you want to use the React API with all its relevant plugins, you can do this:\n\n```js\nconst Selectivity = require(\"selectivity/react\");\n```\n\nThe Selectivity object you receive is the same one as if you'd required `'selectivity'`, but you get\nthe React Component class as `Selectivity.React` so you can use it as follows:\n\n```js\n\u003cSelectivity.React {...props} /\u003e\n```\n\nFinally, if you're an expert (\\*) you can choose to use the VanillaJS API and enable just the\nplugins you want one by one. For example:\n\n```js\nconst Selectivity = require(\"selectivity\");\nrequire(\"selectivity/dropdown\");\nrequire(\"selectivity/inputs/single\");\nrequire(\"selectivity/plugins/ajax\");\nrequire(\"selectivity/plugins/async\");\nrequire(\"selectivity/plugins/submenu\");\n\nconst singleInput = new Selectivity.Inputs.Single({\n    element: document.querySelector(\"...\")\n    /* ... */\n});\n```\n\nAll the modules listed in the table below under _Creating custom builds_ can be required this way.\n\n\\*) Using the VanillaJS API isn't really that hard, but all the examples and documentation assume\nyou're using either the React or the jQuery API, so be prepared that you'll have to figure out a bit\nmore on your own.\n\n### Customization\n\nOnce installed, you may want to customize Selectivity. For example, by specifying custom templates\nor localized strings. While creating a custom build is always an option (see details below), easier\noptions exist.\n\nTo do any basic customization, you'll need a reference to the `Selectivity` object. If you have\ninstalled through Yarn/NPM, you can get this object through\n`const Selectivity = require(\"selectivity\");`. If you're using a jQuery build, the object is exposed\nas `$.Selectivity`. For non-jQuery builds that you included as a script, the object is exposed as\nglobal variable.\n\n#### Example: Customizing localization in a jQuery build\n\n```js\n$.Selectivity.Locale.noResultsForTerm = term =\u003e `No results were found for \u003cb\u003e${escape(term)}\u003c/b\u003e`;\n```\n\nSee [locale.js](https://github.com/arendjr/selectivity/blob/master/src/locale.js) for an overview of\nall localizable messages.\n\n#### Example: Specifying a custom template when installed through NPM\n\n```js\nconst Selectivity = require(\"selectivity\");\nSelectivity.Templates.loading = () =\u003e\n    '\u003cdiv class=\"selectivity-loading\"\u003e\u003cdiv class=\"my-spinner\"\u003e\u003c/div\u003e\u003c/div\u003e';\n```\n\nSee [templates.js](https://github.com/arendjr/selectivity/blob/master/src/templates.js) for an\noverview of all templates that can be customized.\n\n## API\n\nFor usage instructions, please see the Selectivity homepage: https://arendjr.github.io/selectivity/\n\n## Browser Support\n\n-   Chrome\n-   Firefox\n-   Internet Explorer 10+\n-   Safari 6+\n\nNote that while Internet Explorer versions older than 10 are not supported, you might be able to get\nthem to work, possibly with the use of some polyfills. Reports of success or patches to create a\n\"legacy\" build would be welcomed.\n\n## Build System\n\nSelectivity is built modularly and uses Yarn and Gulp as a build system to build its distributable\nfiles. Make sure you have the `yarn` command globally available. Then, inside the project directory,\nrun:\n\n    $ yarn\n\nNow you can generate new distributable files from the sources, using:\n\n    $ yarn build\n\n### Creating custom builds\n\nIf you want to create your own Selectivity library that contains just the modules you need, you can\nuse the following command:\n\n    $ yarn gulp [--api=\u003creact-or-jquery\u003e] --modules=\u003ccomma-separated-module-list\u003e\n\nThe following modules are available:\n\n| Module                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **inputs/email**               | 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).                                                                                                                                                                                                                                                                                                                                                                                          |\n| **inputs/multiple**            | Implements the 'Multiple' input type. If you only want to use Selectivity with single values, you can leave this out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| **inputs/single**              | Implements the 'Single' input type. If you only want to use Selectivity with multiple values, you can leave this out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| **plugins/ajax**               | Convenience module for performing AJAX requests. Needed if you want to use any `ajax` options. If you use this module, you should also include the 'async' module to correctly handle out-of-order replies. This module relies on the presence of the `[fetch()](https://developer.mozilla.org/en-US/docs/Web/API/GlobalFetch/fetch)` method which is only available in modern browsers, so you should either provide a polyfill if you want to support older browsers, or -- if you're creating a jQuery build -- you can use the 'jquery/ajax' module to provide a fallback that uses `$.ajax()` instead. |\n| **plugins/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.                                                                                                                                                                                                                                                                                                                  |\n| **plugins/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 omitted.                                                                                                                                                                                                                                                                                                                    |\n| **plugins/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.                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| **plugins/submenu**            | Extends the default dropdown so that multiple levels of submenus can be created.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| **plugins/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.                                                                                                                                                                                                                                                                              |\n| **plugins/jquery/ajax**        | Provides a fallback to use `$.ajax()` instead of the `fetch()` method for performing AJAX requests. _(Requires jQuery 3.0 or higher)_                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| **plugins/jquery/traditional** | This module allows you to convert an HTML5 `\u003cselect\u003e` form element into a Selectivity instance. The items will be initialized from the `\u003coption\u003e` and `\u003coptgroup\u003e` elements. _(jQuery only)_                                                                                                                                                                                                                                                                                                                                                                                                                |\n| **plugins/react/templates**    | Adds support for React (JSX) templates. Requires `react-dom` to be available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| **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.                                                                                                                                                                                                                                                                                                                                                                                                     |\n| **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.                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| **templates**                  | Default templates to use with Selectivity. If you provide your own templates, you may want to skip this.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n\nNote that the build system automatically resolves dependencies between modules. So for example, if\nyou specify you want the submenu plugin, the dropdown module will be automatically included.\n\nExample:\n\n    $ yarn gulp --api=react --modules=inputs/multiple,dropdown\n\nThis will create a custom build that uses the React API and which has support for selecting multiple\nvalues with a dropdown. The build will be saved in `build/selectivity-custom.js`. There will be no\nplugins available, you will have to provide your own templates with their localizable content, and\nyou cannot use this build for creating a single-select input.\n\nTo display any other options available for custom builds, run `gulp usage`.\n\n### Development server\n\nWhile developing, you can start a development server like this:\n\n    $ yarn start [--api=\u003cjquery-or-react\u003e]\n\nYou can reach the development server on the URL printed on the console (typically\nhttp://localhost:3000), and you'll probably want to open one of the demos there:\n\n-   React: http://localhost:3000/demos/custom-react.html (only works if you started with\n    `yarn start --api=react`)\n-   jQuery: http://localhost:3000/demos/custom-jquery.html (only works if you started with\n    `yarn start --api=jquery`)\n-   Zepto: http://localhost:3000/demos/custom-zepto.html (only works if you started with\n    `yarn start --api=jquery`)\n\n## Unit Tests\n\nUnit tests are available and can be ran using the following command:\n\n    $ yarn unit-tests\n\nIf you want to run an individual test, just add `--test=\u003ctest-name\u003e`. Simply provide an invalid test\nname to get a list of all available test names.\n\n## License\n\nSelectivity is made available under the [MIT license](LICENSE).\n\n## Contributing\n\nTo read more about guidelines for submitting pull requests, please read the\n[Contributing document](CONTRIBUTING.md).\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farendjr%2Fselectivity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farendjr%2Fselectivity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farendjr%2Fselectivity/lists"}