AngularJS - MultiSelect Component

AngularJS MultiSelect is a lightweight reuasble component and includes all in one UI for selection and autocomplete.

Table of contents

• Features
• Getting started
• API
• Change detection
• Custom styles
• Validation state
• Contributing
• Development
• Want to Contribute?
• Need Help / Support?
• Collection of Other Components
• Changelog
• Credits
• License
• Keywords

Features

• Custom binding to property or object
• Custom option, label, header and footer templates
• Virtual Scroll support with large data sets (>5000 items).
• Infinite scroll
• Keyboard navigation
• Multiselect
• Flexible autocomplete with client/server filtering
• Custom search
• Custom tags
• Append to
• Group items
• Output events
• Accessibility
• Good base functionality test coverage
• Themes

Getting started

Step 1: Install angular-weblineindia-multiselect:

NPM

npm install --save angular-weblineindia-multiselect

YARN

yarn add angular-weblineindia-multiselect

Step 2: Import the NgSelectModule and angular FormsModule module:

import { NgSelectModule } from "angular-weblineindia-multiselect";
import { FormsModule } from "@angular/forms";

@NgModule({
  declarations: [AppComponent],
  imports: [NgSelectModule, FormsModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

Step 3: Include a theme:

To allow customization and theming, angular-weblineindia-multiselect bundle includes only generic styles that are necessary for correct layout and positioning. To get full look of the control, include one of the themes in your application. If you're using the Angular CLI, you can add this to your styles.scss or include it in .angular-cli.json (Angular v5 and below) or angular.json (Angular v6 onwards).

@import "angular-weblineindia-multiselect/themes/default.theme.css";
// ... or
@import "angular-weblineindia-multiselect/themes/material.theme.css";

Step 4 (Optional): Configuration

You can also set global configuration and localization messages by injecting NgSelectConfig service, typically in your root component, and customize the values of its properties in order to provide default values.

  constructor(private config: NgSelectConfig) {
      this.config.notFoundText = 'Custom not found';
      this.config.appendTo = 'body';
      // set the bindValue to global config when you use the same
      // bindValue in most of the place.
      // You can also override bindValue for the specified template
      // by defining `bindValue` as property
      // Eg : <ng-select bindValue="some-new-value"></ng-select>
      this.config.bindValue = 'value';
  }

SystemJS

If you are using SystemJS, you should also adjust your configuration to point to the UMD bundle. In your systemjs config file, map needs to tell the System loader where to look for angular-weblineindia-multiselect:

map: {
  'angular-weblineindia-multiselect': 'node_modules/angular-weblineindia-multiselect/bundles/ng-select.umd.js',
}

API

Inputs

Input	Type	Default	Required	Description
[addTag]	boolean | ((term: string) => any | Promise<any>)	false	no	Allows to create custom options.
addTagText	string	Add item	no	Set custom text when using tagging
appearance	string	underline	no	Allows to select dropdown appearance. Set to outline to add border instead of underline (applies only to Material theme)
appendTo	string	null	no	Append dropdown to body or any other element using css selector. For correct positioning body should have position:relative
bindValue	string	-	no	Object property to use for selected model. By default binds to whole object.
bindLabel	string	label	no	Object property to use for label. Default label
[closeOnSelect]	boolean	true	no	Whether to close the menu when a value is selected
clearAllText	string	Clear all	no	Set custom text for clear all icon title
[clearable]	boolean	true	no	Allow to clear selected value. Default true
[clearOnBackspace]	boolean	true	no	Clear selected values one by one when clicking backspace. Default true
[compareWith]	(a: any, b: any) => boolean	(a, b) => a === b	no	A function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection(model). A boolean should be returned.
dropdownPosition	bottom | top | auto	auto	no	Set the dropdown position on open
[groupBy]	string | Function	null	no	Allow to group items by key or function expression
[groupValue]	(groupKey: string, cildren: any[]) => Object	-	no	Function expression to provide group value
[selectableGroup]	boolean	false	no	Allow to select group when groupBy is used
[selectableGroupAsModel]	boolean	true	no	Indicates whether to select all children or group itself
[items]	Array<any>	[]	yes	Items array
[loading]	boolean	-	no	You can set the loading state from the outside (e.g. async items loading)
loadingText	string	Loading...	no	Set custom text when for loading items
labelForId	string	-	no	Id to associate control with label.
[markFirst]	boolean	true	no	Marks first item as focused when opening/filtering.
[isOpen]	boolean	-	no	Allows manual control of dropdown opening and closing. True - won't close. False - won't open.
maxSelectedItems	number	none	no	When multiple = true, allows to set a limit number of selection.
[hideSelected]	boolean	false	no	Allows to hide selected items.
[multiple]	boolean	false	no	Allows to select multiple items.
notFoundText	string	No items found	no	Set custom text when filter returns empty result
placeholder	string	-	no	Placeholder text.
[searchable]	boolean	true	no	Allow to search for value. Default true
[readonly]	boolean	false	no	Set ng-select as readonly. Mostly used with reactive forms.
[searchFn]	(term: string, item: any) => boolean	null	no	Allow to filter by custom search function
[searchWhileComposing]	boolean	true	no	Whether items should be filtered while composition started
[trackByFn]	(item: any) => any	null	no	Provide custom trackBy function
[clearSearchOnAdd]	boolean	true	no	Clears search input when item is selected. Default true. Default false when closeOnSelect is false
[editableSearchTerm]	boolean	false	no	Allow to edit search query if option selected. Default false. Works only if multiple is false.
[selectOnTab]	boolean	false	no	Select marked dropdown item using tab. Default false
[openOnEnter]	boolean	true	no	Open dropdown using enter. Default true
[typeahead]	Subject	-	no	Custom autocomplete or advanced filter.
[minTermLength]	number	0	no	Minimum term length to start a search. Should be used with typeahead
typeToSearchText	string	Type to search	no	Set custom text when using Typeahead
[virtualScroll]	boolean	false	no	Enable virtual scroll for better performance when rendering a lot of data
[inputAttrs]	{ [key: string]: string }	-	no	Pass custom attributes to underlying input element
[tabIndex]	number	-	no	Set tabindex on ng-select
[keyDownFn]	($event: KeyboardEvent) => bool	true	no	Provide custom keyDown function. Executed before default handler. Return false to suppress execution of default key down handlers

Outputs

Output	Description
(add)	Fired when item is added while [multiple]="true". Outputs added item
(blur)	Fired on select blur
(change)	Fired on model change. Outputs whole model
(close)	Fired on select dropdown close
(clear)	Fired on clear icon click
(focus)	Fired on select focus
(search)	Fired while typing search term. Outputs search term with filtered items
(open)	Fired on select dropdown open
(remove)	Fired when item is removed while [multiple]="true"
(scroll)	Fired when scrolled. Provides the start and end index of the currently available items. Can be used for loading more items in chunks before the user has scrolled all the way to the bottom of the list.
(scrollToEnd)	Fired when scrolled to the end of items. Can be used for loading more items in chunks.

Methods

Name	Description
open	Opens the select dropdown panel
close	Closes the select dropdown panel
focus	Focuses the select element
blur	Blurs the select element

Other

Name	Type	Description
[ngOptionHighlight]	directive	Highlights search term in option. Accepts search term. Should be used on option element. README
NgSelectConfig	configuration	Configuration provider for the NgSelect component. You can inject this service and provide application wide configuration.
SELECTION_MODEL_FACTORY	service	DI token for SelectionModel implementation. You can provide custom implementation changing selection behaviour.

Custom selection logic

angular-weblineindia-multiselect allows to provide custom selection implementation using SELECTION_MODEL_FACTORY. To override default logic provide your factory method in your angular module.

// app.module.ts
providers: [
    { provide: SELECTION_MODEL_FACTORY, useValue: <SelectionModelFactory>CustomSelectionFactory }
]

// selection-model.ts
export function CustomSelectionFactory() {
    return new CustomSelectionModel();
}

export class CustomSelectionModel implements SelectionModel {
    ...
}

Change Detection

angular-weblineindia-multiselect component implements OnPush change detection which means the dirty checking checks for immutable data types. That means if you do object mutations like:

this.items.push({ id: 1, name: "New item" });

Component will not detect a change. Instead you need to do:

this.items = [...this.items, { id: 1, name: "New item" }];

This will cause the component to detect the change and update. Some might have concerns that this is a pricey operation, however, it is much more performant than running ngDoCheck and constantly diffing the array.

Custom styles

If you are not happy with default styles you can easily override them with increased selector specificity or creating your own theme. This applies if you are using no ViewEncapsulation or adding styles to global stylesheet. E.g.

<ng-select class="custom"></ng-select>

.ng-select.custom {
  border: 0px;
  min-height: 0px;
  border-radius: 0;
}
.ng-select.custom .ng-select-container {
  min-height: 0px;
  border-radius: 0;
}

If you are using ViewEncapsulation, you could use special ::ng-deep selector which will prevent scoping for nested selectors altough this is more of a workaround and we recommend using solution described above.

.ng-select.custom ::ng-deep .ng-select-container {
  min-height: 0px;
  border-radius: 0;
}

Validation state

By default when you use reactive forms validators or template driven forms validators css class ng-invalid will be applied on ng-select. You can show errors state by adding custom css style

ng-select.ng-invalid.ng-touched .ng-select-container {
  border-color: #dc3545;
  box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075), 0 0 0 3px #fde6e8;
}

Testing

yarn run test
or
yarn run test:watch

Want to Contribute?

• Created something awesome, made this code better, added some functionality, or whatever (this is the hardest part).
• Fork it.
• Create new branch to contribute your changes.
• Commit all your changes to your branch.
• Submit a pull request.

---

Collection of Components

We have built many other components and free resources for software development in various programming languages. Kindly click here to view our Free Resources for Software Development.

---

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

Credits

angular-weblineindia-multiselect is inspired by @ng-select/ng-select.

License

MIT

Keywords

angularjs-multiselect, multiselect, ui-select, dropdown-component, angular-multiselect, multiselect-component, angular-autocomplete