# ember-advanced-combobox > Swiss-knife ember combobox Latest version **5.1.8** (published 2022-04-27) · 0 weekly downloads ## Install ```sh npm install ember-advanced-combobox pnpm add ember-advanced-combobox yarn add ember-advanced-combobox bun add ember-advanced-combobox ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 5.1.8 | | Published | 2022-04-27 | | First published | 2016-07-24 | | Weekly downloads | 0 | | TypeScript types | none | | Module format | CommonJS | | Node | 12.* \|\| 14.* \|\| >= 16 | | Dependencies | 8 | | Unpacked size | 94.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 7 | | Author | Annotation | | Maintainers | ikvasnicka, annotationsro, chiffie, pavol.slany | | Keywords | ember-addon, combobox, dropdown | ## Links - npm: https://www.npmjs.com/package/ember-advanced-combobox - Repository: https://github.com/AnnotationSro/ember-advanced-combobox - Issues: https://github.com/AnnotationSro/ember-advanced-combobox/issues - npm.io page: https://npm.io/package/ember-advanced-combobox ## Dependencies (8) - [cash-dom](https://npm.io/package/cash-dom.md) 8.1.1 - [popper.js](https://npm.io/package/popper.js.md) 1.14.6 - [ember-cli-babel](https://npm.io/package/ember-cli-babel.md) ^7.26.6 - [ember-auto-import](https://npm.io/package/ember-auto-import.md) 1.11.3 - [ember-cli-htmlbars](https://npm.io/package/ember-cli-htmlbars.md) ^5.7.1 - [ember-cli-node-assets](https://npm.io/package/ember-cli-node-assets.md) ^0.2.2 - [element-resize-detector](https://npm.io/package/element-resize-detector.md) 1.2.3 - [ember-classic-decorator](https://npm.io/package/ember-classic-decorator.md) ^2.0.0 ## Recent versions - 5.1.8 (latest) — 2022-04-27 - 5.1.7 — 2022-04-27 - 5.1.6 — 2022-04-17 - 5.1.5 — 2022-04-17 - 5.1.4 — 2022-04-17 - 5.1.3 — 2022-04-15 - 5.1.2 — 2022-02-28 - 5.1.1 — 2021-10-28 - 5.1.0 — 2021-10-25 - 5.0.1 — 2021-09-27 - 5.0.0 — 2021-09-24 - 4.0.0 — 2021-09-23 - 3.5.0 — 2021-08-17 - 3.4.7 — 2021-05-18 - 3.4.6 — 2021-05-07 - … 160 more at https://npm.io/package/ember-advanced-combobox/versions ## README # Ember-advanced-combobox [![Build Status](https://travis-ci.org/AnnotationSro/ember-advanced-combobox.svg?branch=master)](https://travis-ci.org/AnnotationSro/ember-advanced-combobox) Ember combobox that can (beside others): - filter items - sort items - multiselect items - mobile support ("almost" as native) - lazy loading of combobox items * Ember.js v3.20 or above * Ember CLI v3.20 or above * Node.js v12 or above We use [BrowserStack](https://www.browserstack.com/) to make sure this addon works on all browsers. ## Installation **Warning: works for Ember >= 2.8.0** ``` ember install ember-advanced-combobox ``` This addon uses FontAwesome by default - **at the moment you have to provide it for yourself** (this addon does not install it for you). You can however use any font icon set you want, but do not forget to configure this addon (more in section *Global configuration* -> propery *icons*) __Basic usage__ ``` {{combo-box valueList=valueList selected=selectedItem itemKey='itemKey' itemLabel='itemLabel' onSelected=(action 'onSelected') }} ``` __For more usage examples see dummy application.__ | Configuration option | Description | |----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | valueList | Array of items in combobox - can be a plain JSON array or Ember MutableArray (note: either `valueList`, `valuePromise` or `lazyCallback` must be provided) | | valuePromise | Promise - when evaluated, the result will be used as `valueList` (note: either `valueList`, `valuePromise` or `lazyCallback` must be provided) | | lazyCallback |callback to retrieve new combobox list items - usefull for lazy-loaded comboboxes (note: either `valueList`, `valuePromise` or `lazyCallback` must be provided) | itemKey | Name of the property of valueList items to be used is key to identify items | | itemLabel | Name of the property of valueList items to be used as; can be string or function label | | selected | Key of currently selected item | | onSelected | Action callback that will be called when user selects an item | |disabledWhenEmpty | Combobox will be disabled, when there are no options in dropdown menu (recommened to set to `false` when used with `valuePromise`) (default: `true`)| | multiselect | boolean value; it `true` user can select multiple items (default is `false`) | | canFilter | boolean value; if `true` user can filter values in the dropdown - filter is case- and accent- insensitive fulltext search | | disabled | boolean value | | orderBy | Name of the property of valueList items to be used to sort the items in dropdown. If `orderBy` is not provided, items in dropdown will not be sorted. | | minLazyCharacters | overrides `minLazyCharacters` (see global configuration section)| | preselectFirst | boolean value; if `true` combobox will automatically select the first item in the dropdown. | | onDropdownShow | Action callback called when dropdown is going to show | | onDropdownHide | Action callback called when dropdown is going to hide | | showDropdownButton | boolean value; if `false` the dropdown button will be hidden (default is `true`) | | itemLabelForSelectedPreview | string value of function; customize how selected value looks like in the combobox (only for single select combobox); default is the same property as `itemLabel` | | showLabelWhenDisabled | boolean; `false` when combobox should be empty when disabled (default is `false`) | | showChooseLabel | boolean; `false` 'chooseLabel' should be shown - see global configuration as well (default is `true`) | | showEmptySelectionLabel | boolean; `false` 'emptySelectionLabel' should be shown - see global configuration as well (default is `true`) | | maxDropdownHeight | number; max height of dropdown (in pixels) - optional, if not set, dropdown will be stretched to the max height to be still visible in the page | | emptySelectionLabel | overrides `emptySelectionLabel` (see global configuration section)| | chooseLabel | overrides `chooseLabel` (see global configuration section)| | pagination| boolean (default: false); `true` if you want items in dropdown to be fetched with pagination| | pageSize| number (default: 10)| | showDropdownOnClick| boolean (default: true); `true` if dropdown should be opened on click| | confirmInputValueOnBlur| boolean (default: false)| when set to `true`, user can enter value into the filter and DID NOT select filtered value in the dropdown - he can just click outside the combobox, and the value will still be selected| | hideSelected| boolean (default: false)| when set to `true` selected value will be hidden| |onDisabledCallback| callback that will be called when component changes its disabled or labelOnly state| |dropdownIcon| custom css class for dropdown icon| |onDropdownIconClicked| callback called when dropdown icon is clicked, if callback returns false, dropdown is not opened afterwards| |noValueLabel| default value, if empty 'valueList' is provided| Also note that if there is only one item available in combobox, it will be automatically selected. ## Styling Most often you would like to style the mobile version of combobox. To do this you can make use of following CSS classes: - ```.combobox-mobile-dialog ``` - dialog itself (container for all other elements) - ```.header ``` - DIV above the dialog - ```.footer ``` - DIV below the dialog (contains buttons) - ```.btn-cancel ``` - button to cancel dialog - ```.btn-accept ``` - button to confirm selection (for multiselect combobox only) ## Global configuration | Configuration option | Description | Default value | |-----------------------|--------------------------------------------------------------------------------------------------------|--------------------| | emptySelectionLabel | Label shown when no value is selected | "" | | chooseLabel | Label shown when dropdown is visible | "Choose:" | | multiselectValueLabel | Label shown when there are multiple values selected - it appends number of selected items at the end | "Selected items: " | | asyncLoaderStartLabel | Label shown when valuePromise is being evaluated | "Loading..." | | emptyValueList | Label shown when there are no items in dropdown | "No items" | | mobileFilterPlaceholder| Placeholder for filter input in mobile dropdown | "Enter filter here" | | mobileOkButton| Text for "OK" button in mobile dropdown | "Confirm" | | mobileCancelButton| Text for "Cancel" button in mobile dropdown | "Cancel" | | lazyDebounceTime | debounce time (in msec) when typing - used for lazy loading of comobobox items | 1000 | | minLazyCharacters | minimum number of characters to trigger lazy load fetch | 3 | | icons | JSON of font icons used | see example below | |onDisabledCallback| | callback that will be called when component changes its disabled or labelOnly state| There are 2 ways to configure the combobox: using `config/environment.js` or by injecting service `ember-advanced-combobox/adv-combobox-configuration-service`: ### environment.js configuration Add this to your `config/environment.js` file: ``` var ENV = { //------------------------ "ember-advanced-combobox": { emptySelectionLabel: "", chooseLabel: "Choose:", multiselectValueLabel: "Selected items: ", asyncLoaderStartLabel: "Loading...", emptyValueList: 'No items', mobileFilterPlaceholder: 'Enter filter here', mobileOkButton: 'Confirm', mobileCancelButton: 'Cancel', lazyDebounceTime: 1000, minLazyCharacters: 3, icons: { dropdown: 'fa fa-chevron-down', 'checkbox-checked': 'fa fa-check-square-o', 'checkbox-unchecked': 'fa fa-square-o', loading: 'fa fa-circle-o-notch fa-spin fa-fw' } } //--------------------------- } ``` Configuration service `ember-advanced-combobox/adv-combobox-configuration-service` enables you to customize the combobox at runtime (e.g. beacuse of translations): ``` comboboxConfig: Ember.inject.service('adv-combobox-configuration-service'); this.get('comboboxConfig').setConfiguration("emptySelectionLabel", "some value"); ``` --- _Source: https://npm.io/package/ember-advanced-combobox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._