@ng-select/ng-select

What is @ng-select/ng-select?

@ng-select/ng-select is a highly customizable Angular component for creating select dropdowns. It provides a wide range of features including single and multiple selection, custom templates, filtering, and more.

What are @ng-select/ng-select's main functionalities?

Single Selection

This feature allows users to select a single item from a dropdown list. The `items` input takes an array of objects, and `bindLabel` specifies the property to display in the dropdown.

<ng-select [items]="cities" bindLabel="name" placeholder="Select a city"></ng-select>

Multiple Selection

This feature enables users to select multiple items from the dropdown. Setting the `multiple` input to `true` allows for multiple selections.

<ng-select [items]="cities" bindLabel="name" [multiple]="true" placeholder="Select cities"></ng-select>

Custom Templates

Custom templates allow for more control over the appearance of the dropdown items. The `ng-option-tmp` directive can be used to define a custom template for each item.

<ng-select [items]="cities" bindLabel="name" placeholder="Select a city">
  <ng-template ng-option-tmp let-item="item" let-index="index">
    <div class="custom-option">
      <span>{{item.name}}</span>
    </div>
  </ng-template>
</ng-select>

Filtering

The filtering feature allows users to search through the dropdown items. Setting the `searchable` input to `true` enables this functionality.

<ng-select [items]="cities" bindLabel="name" [searchable]="true" placeholder="Select a city"></ng-select>

Async Data

This feature supports loading data asynchronously. The `items` input can take an observable, and the dropdown will update as the data is loaded.

<ng-select [items]="cities$ | async" bindLabel="name" placeholder="Select a city"></ng-select>

Other packages similar to @ng-select/ng-select

ngx-select-dropdown

ngx-select-dropdown is another Angular package for creating dropdowns. It offers similar functionalities such as single and multiple selection, custom templates, and filtering. However, it may not be as feature-rich or customizable as @ng-select/ng-select.

ng-multiselect-dropdown

ng-multiselect-dropdown is focused on providing a multi-select dropdown component for Angular. It supports features like filtering and custom templates but is primarily designed for multiple selections, unlike @ng-select/ng-select which supports both single and multiple selections.

angular-ng-autocomplete

angular-ng-autocomplete is an Angular component for creating autocomplete dropdowns. It provides features like filtering and custom templates, similar to @ng-select/ng-select, but is more focused on autocomplete functionality rather than general dropdowns.

README

Angular ng-select - All in One UI Select, Multiselect and Autocomplete

See Demos or try in Plunker

Table of contents

• Features
• Getting started
• Roadmap
• Examples
  • API
  • Basic example
  • Flexible autocomplete
  • Custom display and option templates
• Contributing
• Development
• Credits

Features

• Custom bindings to property or object
• Custom option and label templates
• Virtual Scroll support with large data sets (>5000 items).
• Keyboard navigation
• Correct keyboard events behaviour
• Multiselect
• Flexible autocomplete with client/server filtering

Warning

Library is under active development and may not work as expected until stable 1.0.0 release.

Getting started

After installing the above dependencies, install ng-select via:

npm install --save @ng-select/ng-select

Once installed you need to import our main module:

import {NgSelectModule} from '@ng-select/ng-select';

The only remaining part is to list the imported module in your application module.:

import {NgSelectModule} from '@ng-select/ng-select';

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

You can also configure global configuration and localization messages by using NgSelectModule.forRoot:

NgSelectModule.forRoot({notFoundText: 'Your custom not found text', typeToSearchText: 'Your custom type to search text'})

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 ng-select:

map: {
  '@ng-select/ng-select': 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js',
}

Roadmap

• Custom binding to property or object
• Custom option and label templates
• Virtual Scroll support with large data sets (>5000 items).
• Filter data by display text
• Filter data by custom filter function
• Expose useful events like blur, change, focus, close, open ...
• Correct keyboard events behaviour
• Integration app generated with angular-cli
• Good base functionality test coverage
• Multiselect support
• Autocomplete
• Custom tags
• Accessibility

API

Input	Type	Default	Required	Description
[items]	Array	[]	yes	Items array
bindLabel	string	label	no	Object property to use for label. Default label
bindValue	string	-	no	Object property to use for selected model. By default binds to whole object.
[clearable]	boolean	true	no	Allow to clear selected value. Default true
placeholder	string	-	no	Placeholder text.
notFoundText	string	No items found	no	Set custom text when filter returns empty result
typeToSearchText	string	Type to search	no	Set custom text when using Typeahead
[typeahead]	Subject	-	no	Custom autocomplete or filter.

Output	Description
(focus)	Fired on select focus
(blur)	Fired on select blur
(change)	Fired on selected value change
(open)	Fired on select dropdown open
(close)	Fired on select dropdown close

Change Detection

Ng-select 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.push({id: 1, name: 'New item'})
this.items = [...this.items];

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.

Examples

Basic example

This example in Plunkr

@Component({
    selector: 'cities-page',
    template: `
        <label>City</label>
        <ng-select [items]="cities"
                   bindLabel="name"
                   bindValue="id"
                   placeholder="Select city"
                   [(ngModel)]="selectedCityId">
        </ng-select>
        <p>
            Selected city ID: {{selectedCityId}}
        </p>
    `
})
export class CitiesPageComponent {
    cities = [
        {id: 1, name: 'Vilnius'},
        {id: 2, name: 'Kaunas'},
        {id: 3, name: 'Pabradė'}
    ];
    selectedCityId: any;
}

Flexible autocomplete

This example in Plunkr

In case of autocomplete you can get full control by creating simple EventEmmiter and passing it as an input to ng-select. When you type text, ng-select will fire events to EventEmmiter to which you can subscribe and control bunch of things like debounce, http cancellation and so on.

@Component({
    selector: 'select-autocomplete',
    template: `
        <label>Search with autocomplete in Github accounts</label>
        <ng-select [items]="items"
                   bindLabel="login"
                   placeholder="Type to search"
                   [typeahead]="typeahead"
                   [(ngModel)]="githubAccount">
            <ng-template ng-option-tmp let-item="item">
                <img [src]="item.avatar_url" width="20px" height="20px"> {{item.login}}
            </ng-template>
        </ng-select>
        <p>
            Selected github account:
            <span *ngIf="githubAccount">
                <img [src]="githubAccount.avatar_url" width="20px" height="20px"> {{githubAccount.login}}
            </span>
        </p>
    `
})
export class SelectAutocompleteComponent {

    githubAccount: any;
    items = [];
    
    // event emmiter is just RxJs Subject
    typeahead = new EventEmitter<string>();

    constructor(private http: HttpClient) {
        this.typeahead
            .distinctUntilChanged()
            .debounceTime(200)
            .switchMap(term => this.loadGithubUsers(term))
            .subscribe(items => {
                this.items = items;
            }, (err) => {
                console.log(err);
                this.items = [];
            });
    }

    loadGithubUsers(term: string): Observable<any[]> {
        return this.http.get<any>(`https://api.github.com/search/users?q=${term}`).map(rsp => rsp.items);
    }
}

Custom display and option templates

This example in Plunkr

To customize look of input display or option item you can use ng-template with ng-label-tmp or ng-option-tmp directives applied to it.

import {Component, NgModule} from '@angular/core';
import {BrowserModule} from '@angular/platform-browser';
import {FormsModule} from '@angular/forms';
import {NgSelectModule} from '@ng-select/ng-select';
import {HttpClient, HttpClientModule} from '@angular/common/http';

@Component({
    selector: 'select-custom-templates',
    template: `
        <label>Demo for ng-select with custom templates</label>
        <ng-select [items]="albums"
                   [(ngModel)]="selectedAlbumId"
                   bindLabel="title"
                   bindValue="id"
                   placeholder="Select album">
            <ng-template ng-label-tmp let-item="item">
               <b>({{item.id}})</b> {{item.title}}
            </ng-template>
            <ng-template ng-option-tmp let-item="item">
                <div>Title: {{item.title}}</div>
                <small><b>Id:</b> {{item.id}} | <b>UserId:</b> {{item.userId}}</small>
            </ng-template>
        </ng-select>
        <p>Selected album ID: {{selectedAlbumId || 'none'}}</p>
    `
})
export class SelectCustomTemplatesComponent {
    albums = [];
    selectedAlbumId = null;

    constructor(http: HttpClient) {
        http.get<any[]>('https://jsonplaceholder.typicode.com/albums').subscribe(albums => {
            this.albums = albums;
        });
    }
}

More demos

Visit demos for more examples.

Contributing

Contributions are welcome. You can start by looking at issues with label Help wanted or creating new Issue with proposal or bug report. Note that we are using https://conventionalcommits.org/ commits format.

Development

Perform the clone-to-launch steps with these terminal commands.

Run demo page in watch mode

git clone https://github.com/ng-select/ng-select
cd ng-select
yarn
yarn run start

Testing

yarn run test
or
yarn run test-watch

Publishing to npm

./prerelease.sh

Script will pull from master, run command npm run release and npm run build. After this you need to check if CHANGELOG is correct and run npm publish --access=public from dist folder.

Deploy demo to gh-pages

npm run gh-pages

// after swith to gh-pages branch run
./publish-demo.sh

Credits

This component is inspired by React select and Vitual scroll. Check theirs amazing work and components :)

Changelog

0.3.1 (2017-10-20)

Bug Fixes

• add typeahead css class binding on host (#92) (51d7036)

<a name="0.3.0"></a>