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-function-return-type eslint rule
• Remove deepMerge dependency.

Contributors

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