Changes

🚀 Features

• Support <option> label attribute @Xon (#1289)
• add KMP search algorithm (gated by build flag) @midzer (#1277)

🐛 Bug Fixes

• Remove role="textbox" from search input, per a11y practices. #941 @mlinnetz (#1285)

Contributors

@Xon, @midzer, @mlinnetz and Mike Linnetz

Changes

🚨 Breaking changes

• Changes to setChoices & clearChoices adjust how the selection and new choices combine when using replaceChoices: true is used to better match v10.2.0 and v11.0.3 behavior.
  • To remove duplication, consider using the configuration optionduplicateItemsAllowed: false, or use the setChoices's new 6th argument replaceItems:true

🐛 Bug Fixes

• Fix setChoices & clearChoices related regressions @Xon (#1278 #1283)
• Revert "Do not preventDefault on item to support dragging" #1266 @Xon (#1282)

Chore

• Add e2e test for dropdown behavior on item mouse down/click
• Add e2e test for serveral setChoices/clearChoices actions

Contributors

@Xon

Changes

🐛 Bug Fixes

• Fix setChoices regression in v11.0.4, where replaceChoices argument would deselect selected items. Fixes #1278 @Xon (#1279)

Contributors

@Xon

Changes

🚀 Features

• Do not preventDefault on item to support dragging @joeworkman (#1266)

🐛 Bug Fixes

• Fix v11 setChoice performance regression @Xon (#1276)
• Fix renderSelectedChoices option when all choices are selected @Xon (#1274)
• Fix v11 regression for disabled placeholder option handling @Xon (#1273)
• Fix v11 regression where clearChoices (and setChoices with replaceChoices:true) did not remove selected items @Xon (#1272)
• Fix v11 regression where duplicateItemsAllowed option did not work with select-one/select-multiple @Xon (#1271)
• Fix: Reached maximum item limit notice is not cleared after removing selections @ticktackk (#1270)
• Fix: Disabled options are not visible (#1257) @ticktackk (#1269)
• Fix: Clear button reverses items order @ticktackk (#1265)
• Fix tab => direction keys handling with disabled search @zoglo (#1260)
• Improve cjs compatibility by removing pinned "module" type in package.json @roma-formio (#1254)

🔧 Maintenance

• Bump vitest and @vitest/coverage-v8 @dependabot (#1264)
• Bump undici from 5.28.4 to 5.28.5 @dependabot (#1255)
• Bump vite from 5.4.6 to 5.4.14 @dependabot (#1256)

Contributors

@Xon, @dependabot, @joeworkman, @roma-formio, @ticktackk and @zoglo

Changes

🐛 Bug Fixes

• Fix tab => direction keys handling in single-select mode @Xon (#1242)
• Fix shift key handling when navigating with tab @zoglo (#1245)
• Fix HTML comments were copied from backing <option> and were rendered as text @Xon (#1244)
• Fix multiple-select mode "No choices to choose from" is sometimes displayed even if there are choices @Xon (#1243)
• Fix Notice for max item limit is removed permanently if you keep typing @Xon (#1241)
• Fix search was not stopped when leaving focus with esc key @zoglo (#1240)
• Fix tab and esc keys handling @zoglo (#1239)
• Fix input text - method setValue didn't work @Xon (#1211)

🔧 Maintenance

• Update v11 event payload in README.md @DarrenSG (#1226)
• Chore: Replace enum KeyCodeMap with const object @Xon (#1210)
• Bump rollup from 4.20.0 to 4.22.4 @dependabot (#1208)
• Bump vite from 5.3.5 to 5.4.6 @dependabot (#1205)

Contributors

@DarrenSG, @Xon, @dependabot, @dependabot[bot] and @zoglo

Changes

🚀 Features

• duplicateItemsAllowed option is now respected by setChoices() method @Xon (#1198)
• Pass getClassNames as the 3rd argument to callbackOnCreateTemplates callback @Xon (#1190)

🐛 Bug Fixes

• Fix various opt-group handling issues @Xon (#1200)
• Fix clearChoices() would remove items, and clear the search flag @Xon (#1196)
• Fix "no choices to choose from"/"no results found" notice did not reliably trigger @Xon (#1192 #1197)
• Fix regression of UnhighlightItem event not firing (#1173) @Xon (#1194)
• Fix regression where webpack doesn't permit importing scss/css @tagliala (#1193)

🔧 Maintenance

• Add autocomplete example to end-to-end tests @Xon (#1199)
• Add e2e tests for "no choices" behavior to match v10 @Xon (#1186)

Contributors

@Xon and @tagliala

🐛 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

⚠ 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...

⚠ 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 ...

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