v11.0.1

🐛 Bug Fixes

• Fix form reset/clearStore method @Xon (#1181)

🔧 Maintenance

• Add paste & search e2e tests @Xon (#1179)
• Cleanup adding classes to generated elements @Xon (#1183)

Contributors

@Xon

v11.0.0

⚠ BREAKING CHANGES (from v10.2.0)

• allowHtml now defaults to false.
• Update to using Fuse.js v7.0.0
• Update choices.js package to be an ES module, and use 'subpath exports' to expose multiple versions (UMD, MTS bundles, can product CJS bundles but it is not enabled by default).
• Provide "fuse full" (default choices.js, ~19.9KB), or "fuse basic" (choices.search-basic.js ~18.8KB) or "prefix filter" (choices.search-filter.js ~14.6KB) based on how much Fuse.js is included.
• Templates/text functions now escape ' characters for display.
• addItemText/uniqueItemText/customAddItemText are now called with the value argument already escaped.
• For select-one and select-multiple, the placeholder value is pulled from config.placeholderValue="..." or <select data-placeholder="..."> before attempting to extract a placeholder from the options list. #912 #567 #843
• enter key now consistently opens/closes the dropdown instead of the behavior varying depending on backing element or internal state of the highlighted choice
• Mutation APIs setChoiceByValue/setChoices/setValue now throw an error if the Choices instance was not initialized or multiple choices instances where initialized on the same element. Prevents bad internal states from triggering unexpected errors #1129
• Improve consistency of the choice event firing. choice event now occurs after the addItem event
• Trigger a search event (with empty value and 0 resultCount) when search stops
• Update polyfills to include Element.prototype.replaceChildren
• A number of internal APIs have been extensively refactored, this includes typescript class names.
• Typescript source mapping files .d.ts.map are no longer generated and various .test.d.ts files are no longer generated

🚀 Features

• Improve performance of search/filtering with large number of choices.
• Improve performance of rendering a large number of items or choices and adding/removing items.
  • Stopping a search or adding many items quickly may cause micro-stutters on lower end devices.
• Add closeDropdownOnSelect option, controls how the dropdown is close after selection is made. #636 #973 #1012
• Allow choices.js to be imported on nodejs, useful for tests and also server side rendering. As windows.document is by default not defined, the default template rendering will not function. The callbackOnCreateTemplates callback must be used. #861
• config.classNames now accept arrays to support multiple classes. #1121 #1074 #907 #832
• The original option list for the select is not destroyed, and all loaded choices are serialised to HTML for better compatibility with external javascript. #1053 #1023
• New singleModeForMultiSelect feature to treat a select-single as if it was a select-multiple with a max item count of 1, and still auto-close the dropdown and swap the active item on selection.
• Remove item text can be localized.
• Allow user-created choices for selects. #1117 #1114
  • User input is escaped by default. At the risk of XSS attacks this can be disabled by allowHtmlUserInput.
• Render options without a group even if groups are present. #615 #1110
• Read data-labelclass/data-label-description from <option> HTML to drive adding a per-choice CSS label and description text when allowHtml: false.
• Add removeItemButtonAlignLeft option, to control if the remove item button is at the start or the end of the item.
• Add removeChoice method. Removes the choice from the choices.js object and any backing <option> HTML element
• Add refresh method. Reloads choices from the backing <select>s options.
• escapeForTemplate function is passed to the 2nd method of the callbackOnCreateTemplates callback.
• When allowHtml is false, default templates now render escaped html to innerHtml writing to innerText.
  • This provides consistent rendering performance as innerText is quirky and slower than escaped html into innerHtml
• Shadow DOM support #938
• searchResultLimit can be set to -1 for no limit of search results to display.

🐛 Bug Fixes

• HTML escaping of choice/item labels should no longer double escape depending on allowHTML mode.
• Avoid pushing a search to fuse.js which is just additional whitespace to the existing search term
• Replace malicious polyfill with cdnjs. #1161
• Maintain groups in search mode. #1152
• Fix various "first press" bugs on single select dropdowns. #1104
• Fix 'esc' would close the dropdown and also apply to the container resulting in an overlay/modal unexpectedly closing. #1039
• Fix form reset would clear the choices list, but not clear the search bar. #1023
• Fix options would be disabled when choices.js was initialized on a disabled <select> element. #1025
• Fix a search_term element to appear in form submit data. #1049
• Fix 'remove item' button would trigger the change event twice due to placeholder value being used (match html single-select). #892
• Fix optgroups are not preserved when Choices is destroyed #1055
• Fix placeholder config option would be ignored for select boxes which have blank entries.
• Fix data-custom-properties attribute did not serialize to created elements as a json blob as expected. #840 #1155 #543
• Fix multi-select did not correctly resizing when a select option is selected on choices.js initialization.
• Fix clearInput function did not clear the last search.
• Fix addItemFilter would allow empty strings as input to be added for items.
• Fix various issues with double escaping when displaying items/choices depending on allowHTML mode.
• Fix aria-label for placeholders was set to the string null
• Fix searchEnable flag was not respected for select-multiple #1042
• Fix poor error message when Choices is passed a string selector which fails to find the element for Choices to attach to.
• Improve various [aria-*] attribute handling for better lighthouse accessibility scores #1169
• Improve contrast on default CSS by darkening primary item selection color #924
• Fix Choices does not accept an element from an iframe #1057
• Fix Choices was not disable in a <fieldset disabled> #1132
• Fix silent option does not silence warnings about unknown options #1119
• Fix documentation that suggests duplicateItemsAllowed works with select-multiple, when it only works for text. #1123
• Fix quadratic algorithm complexity (aka O(N^2) ) when filtering/search choices.
• Fix search results could be unexpectedly unstable, and that fuseOptions.sortFn was effectively ignored #1106
• Fix select-one placeholder could ignore the non-option placeholder configuration
• Fix search did not trigger to copy&paste events #860 #174
  Fix the page scrolls when you press 'space' on a single select input #1103
• Update typescript definition for removeActiveItems to explicitly mark excludedId as optional #1116

🔧 Chore

• Remove various unused code and redundant tests
• For test html pages, prevent a failing fetch() from breaking the rest of the tests
• Switch from webpack to rollup, and provide esm/umd bundles by default. Enables tree shaking! 3kb-4kb dropped from the umd bundle (aka compatible with the previous produced webpack bundle)
• Switch from mocha to vitest as the test running framework.
• Switch from puppeteer/selenium/cypress to playwright as the end-to-end test running framework.
• Restructure end-to-end tests so html/script blocks are co-located to improve debugability
• Add performance oriented end-to-end tests
• Enable `@typescript-eslint/explicit-func...

v11.0.0-rc8

⚠ BREAKING CHANGES

• allowHtml now defaults to false.
• Update to using Fuse.js v7.0.0
• Update choices.js package to be an ES module, and use 'subpath exports' to expose multiple versions (UMD, MTS bundles, can product CJS bundles but it is not enabled by default).
• Provide "fuse full" (default choices.js, ~19.9KB), or "fuse basic" (choices.search-basic.js ~18.8KB) or "prefix filter" (choices.search-filter.js ~14.6KB) based on how much Fuse.js is included.
• A number of internal APIs have been extensively refactored.
• HTML escaping of choice/item labels should no longer double escape depending on allowHTML mode.
• Templates/text functions now escape ' characters for display.
• addItemText/uniqueItemText/customAddItemText are now called with the value argument already escaped.
• Typescript classes for input data vs internal working data have been adjusted resulting in the Choice/Group/Item typescript classes have been renamed, and aliases left as required.
• For select-one and select-multiple, the placeholder value is pulled from config.placeholderValue="..." or <select data-placeholder="..."> before attempting to extract a placeholder from the options list. #912 #567 #843
• Typescript source mapping files .d.ts.map are no longer generated and various .test.d.ts files are no longer generated
• Improve consistency of the choice event firing. choice event now occurs after the addItem event
• enter key now consistently opens/closes the dropdown instead of the behavior varying depending on backing element or internal state of the highlighted choice
• Mutation APIs setChoiceByValue/setChoices/setValue now throw an error if the Choices instance was not initialized or multiple choices instances where initialized on the same element. Prevents bad internal states from triggering unexpected errors #1129
• Trigger a search event (with empty value and 0 resultCount) when search stops

🚀 Features

• Improve performance of search/filtering with large number of choices.
• Add closeDropdownOnSelect option, controls how the dropdown is close after selection is made. #636 #973 #1012
• Allow choices.js to be imported on nodejs, useful for tests and also server side rendering. As windows.document is by default not defined, the default template rendering will not function. The callbackOnCreateTemplates callback must be used. #861
• config.classNames now accept arrays to support multiple classes. #1121 #1074 #907 #832
• The original option list for the select is not destroyed, and all loaded choices are serialised to HTML for better compatibility with external javascript. #1053 #1023
• New singleModeForMultiSelect feature to treat a select-single as if it was a select-multiple with a max item count of 1, and still auto-close the dropdown and swap the active item on selection.
• Remove item text can be localized.
• Allow user-created choices for selects. #1117 #1114
  • User input is escaped by default. At the risk of XSS attacks this can be disabled by allowHtmlUserInput.
• Render options without a group even if groups are present. #615 #1110
• Read data-labelclass/data-label-description from <option> HTML to drive adding a per-choice CSS label and description text when allowHtml: false.
• Add removeItemButtonAlignLeft option, to control if the remove item button is at the start or the end of the item.
• Add removeChoice method. Removes the choice from the choices.js object and any backing <option> HTML element
• Add refresh method. Reloads choices from the backing <select>s options.
• escapeForTemplate function is passed to the 2nd method of the callbackOnCreateTemplates callback.
• When allowHtml is false, default templates now render escaped html to innerHtml writing to innerText.
  • This provides consistent rendering performance as innerText is quirky and slower than escaped html into innerHtml
• Shadow DOM support #938
• searchResultLimit can be set to -1 for no limit of search results to display.

🐛 Bug Fixes

• Avoid pushing a search to fuse.js which is just additional whitespace to the existing search term
• Replace malicious polyfill with cdnjs. #1161
• Maintain groups in search mode. #1152
• Fix various "first press" bugs on single select dropdowns. #1104
• Fix 'esc' would close the dropdown and also apply to the container resulting in an overlay/modal unexpectedly closing. #1039
• Fix form reset would clear the choices list, but not clear the search bar. #1023
• Fix options would be disabled when choices.js was initialized on a disabled <select> element. #1025
• Fix a search_term element to appear in form submit data. #1049
• Fix 'remove item' button would trigger the change event twice due to placeholder value being used (match html single-select). #892
• Fix optgroups are not preserved when Choices is destroyed #1055
• Fix placeholder config option would be ignored for select boxes which have blank entries.
• Fix data-custom-properties attribute did not serialize to created elements as a json blob as expected. #840 #1155 #543
• Fix multi-select did not correctly resizing when a select option is selected on choices.js initialization.
• Fix clearInput function did not clear the last search.
• Fix addItemFilter would allow empty strings as input to be added for items.
• Fix various issues with double escaping when displaying items/choices depending on allowHTML mode.
• Fix aria-label for placeholders was set to the string null
• Fix searchEnable flag was not respected for select-multiple #1042
• Fix poor error message when Choices is passed a string selector which fails to find the element for Choices to attach to.
• Improve various [aria-*] attribute handling for better lighthouse accessibility scores #1169
• Improve contrast on default CSS by darkening primary item selection color #924
• Fix Choices does not accept an element from an iframe #1057
• Fix Choices was not disable in a <fieldset disabled> #1132
• Fix silent option does not silence warnings about unknown options #1119
• Fix documentation that suggests duplicateItemsAllowed works with select-multiple, when it only works for text. #1123
• Fix quadratic algorithm complexity (aka O(N^2) ) when filtering/search choices.
• Fix search results could be unexpectedly unstable, and that fuseOptions.sortFn was effectively ignored #1106
• Fix select-one placeholder could ignore the non-option placeholder configuration
• Fix search did not trigger to copy&paste events #860 #174
  Fix the page scrolls when you press 'space' on a single select input #1103
• Update typescript definition for removeActiveItems to explicitly mark excludedId as optional #1116

🔧 Chore

• Remove various unused code
• For test html pages, prevent a failing fetch() from breaking the rest of the examples
• Tweak _render loop to avoid duplicating has-changed checks
• Switch from webpack to rollup, and provide esm/cjs/umd bundles by default. Enables tree shaking! ~3kb dropped from the umd bundle (aka compatible with the previous produced webpack bundle)
• Switch from mocha to vitest as the test running framework.
• Switch from puppeteer/selenium/cypress to playwright as the end-to-end test running framework.
• Restructure end-to-end tests so html/script blocks are co-located to improve debugability
• Enable @typescript-eslint/explicit-function-return-type eslint rule
• Remove deepMerge dependency.

Contributors

@Xon, @alanhamlett, @gaetan-hexadog, @joeworkman, @krisre-sigmabold, @stefan-korn, @ticktackk ...

Version 10.2.0

Changes

🚀 Features

• Add JSON support to custom properties @brosua (#1001)
• Allow overwrite of the $choices-z-index variable @Moonlight-Angel (#1034)

🐛 Bug Fixes

• Fix support for non-Latin characters @ousmorez (#1072)
• Correct evaluation of HTML custom properties @brosua (#1001)
• Fix typo on aria-labelledby attribute @comxd (#1026)
• Fix type for parameter on setChoiceByValue @mtriff (#1021)

🔧 Maintenance

• Documentation: Add option "uniqueItemText" and "customAddItemText" to README @Sysix (#1051)

Contributors

@Moonlight-Angel, @Sysix, @brosua, @comxd, @mtriff, @ousmorez, David DIVERRES and Josua Vogel

Version 10.1.0

Changes

🚀 Features

• Add option labelId to improve a11y @brosua (#971)

🐛 Bug Fixes

• Fix first character not appearing in webkit browsers @mtriff (#1010)
• Fix multiple select in Internet Explorer 11 @supermueller (#996)

🔧 Maintenance

• README Fix: Use select-single everywhere, fix missing comma in default options @mysliwietzflorian (#1000)

Contributors

@brosua, @mtriff, @mysliwietzflorian and @supermueller

Version 10.0.0

Changes

🚨 Breaking changes

• Upgrade to Fuse v6 @mtriff (#991)
  • The fuseOptions have changed. See https://fusejs.io/api/options.html for details.
• Introduce allowHTML option to allow people to disable injecting HTML into choices. @victiondev (#984)
  • Previously all Choices elements were set using innerHTML. This had the potential to allow XSS attacks when loading items from external, untrusted sources. This behaviour has been deprecated. The new option allowHTML has been introduced, with the current default to true. The default will change to false in a future release. It is recommended that you set it to false unless you require HTML.
  • As a result of this change, callbackOnCreateTemplates now receives the full configuration object, instead of just classNames. The method signature to match previous versions is now ({ classNames }, data). See the documentation for the updated example.

🐛 Bug Fixes

• Trigger search when clearing the input field with search floor of 0 @daicambruzzi (#992)
• Remove character sanitisation when searching @isaac-mercieca (#990)
• Prevent browser autocomplete suggestions on Choices elements @bobmaerten (#908)
• Fix Sanitization of > Characters @rjorel (#983)

🔧 Maintenance

• Fix typings @mtriff, @victiondev (#985, #986, #987)

Contributors

@bobmaerten, @mtriff, @rjorel, @victiondev, @isaac-mercieca, @daicambruzzi

Version 9.1.0

Changes

Although this is primarily a maintenance release, there have been a couple of large refactorings done (for example, conversion of the library to TypeScript). So, just to be cautious, this is a minor version bump.

🐛 Bug Fixes

• Resolve #780 @jshjohnson (#785)
• Resolve #774 @jshjohnson (#777)
• Resolve #762 @jshjohnson (#767)

🔧 Maintenance

• Switch to dart-sass, fix npm audit issues @mtriff (#979)
• Documentation of input type terms @trbroyles1 (#873)
• Solve deprecated warning using / for division outside of calc() @hans2103 (#976)
• Update README.md @flip111 (#844)
• Fix typo in README.md s/withing/within @JoshuaCrewe (#848)
• Update dependencies, fix GitHub Action workflows @mtriff (#977)
• Fix broken demo link in README.md @bzf (#975)
• Fix a typo in the README: s/seperates/separates @alexwlchan (#807)
• Update release drafter to latest @jshjohnson (#800)
• Convert to typescript @jshjohnson (#795)
• Adds a variable for the z-index @dgrammatiko (#794)
• Resolve #622 and #781 @jshjohnson (#784)
• Resolve #778 @jshjohnson (#783)
• Update polyfill list @jshjohnson (#765)

Contributors

@JoshuaCrewe, @actions-user, @alexwlchan, @bzf, @dgrammatiko, @flip111, @hans2103, @jshjohnson, @mtriff, @trbroyles1 and Joshua Crewe

Version 9.0.1

Changes

🐛 Bug Fixes

• Fix #573 @kzkn (#574)

🔧 Maintenance

• Fix releases @jshjohnson (#761)

Contributors

@jshjohnson, @kzkn and GitHub Action

Version 9.0.0

Changes

🚨 Breaking changes

• Add missing type definitions + rename sortFn @jshjohnson (#734)
• Fix #727 @jshjohnson (#731)

🐛 Bug Fixes

• Remove redundant event listener conditional @jshjohnson (#755)
• Resolve bug #637 @jshjohnson (#754)
• Always hide remove button if no value is selected @bronzehedwick (#744)
• Indent fixed in "choices__list--dropdown" @dios-oleg (#750)
• Resolve bug 473 @jshjohnson (#739)
• Resolve bug 533 @jshjohnson (#736)
• fix setChoices flow @tinovyatkin (#730)

🔧 Maintenance

• Typo. @agamemnus (#759)
• Commit and push built files to master @jshjohnson (#756)
• Upgrade Cypress to 3.6 and use cache in Github Actions @tinovyatkin (#748)
• Fix id types @jshjohnson (#743)
• remove safari test, update snapshots for new macOS, use dependency caching @tinovyatkin (#745)
• Enable test on Safari @tinovyatkin (#737)
• [bug] Override Prettier settings for Demo page @tinovyatkin (#733)
• [TEST] Automatic screenshots comparing and error checking in IE11, Firefox and Chrome @tinovyatkin (#715)
• Add documentation label + headings @jshjohnson (#729)
• Update GitHub action workflows @jshjohnson (#728)
• Fix lint @tinovyatkin (#723)
• Store config in file @jshjohnson (#722)
• Add release drafter @jshjohnson (#720)

🔧 Maintenance

• improve whole-page performance by scoping events handlers @tinovyatkin (#740)
• Code refactoring @jshjohnson (#735)
• speed up getAdjacentEl @tinovyatkin (#726)
• use CSS queries @tinovyatkin (#718)

Contributors

@agamemnus, @bronzehedwick, @dios-oleg, @jshjohnson and @tinovyatkin

Version 8.0.0

This version contains multiple breaking changes:

• The ability to pass multiple elements to one instance of Choices has been removed - now only one element can be associated with Choices (#693)
• The undocumented userDefaults static property has been removed
• The ajax method has been removed. setChoices can now be used to set choices dynamically - more info can be found in the README (#701)
• The addItemFilterFn option has been renamed to addItemFilter and now supports regex's (#699)
• Element.prototype.closest has been added to the required polyfill list (#696)
• The .is-hidden class has been replaced with the hidden attribute (https://github.com/jshjohnson/Choices/pull/691/files)

This version also contains numerous bug fixes, type fixes + tooling improvements 🎉

Big thanks to @tinovyatkin for his contributions to this release!