wilsondonizetti/ng-select

:star: Native angular 5+ select component

Angular ng-select - Lightweight all in one UI Select, Multiselect and Autocomplete

See Demos or try in Plunker

Table of contents

• Features
• Getting started
• Roadmap
• API
• Change detection
• Custom styles
• Examples
  • Basic example
  • Flexible autocomplete
  • Custom display templates
  • Validation state
• Contributing
• Development
• Inspiration

Features

• Custom model bindings to property or object
• Custom option, label, header and footer templates
• Virtual Scroll support with large data sets (>5000 items).
• Keyboard navigation
• Multiselect
• Flexible autocomplete with client/server filtering
• Custom tags
• Append to body

Warning

Library is under active development and may have API breaking changes until stable 1.0.0 release or subsequent major versions after 1.0.0.

Getting started

Step 1: Install ng-select:

NPM

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

YARN

yarn add @ng-select/ng-select

Step 2: Import the component module:

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

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

Step 3: Include a theme:

To allow customization and theming, ng-select 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.

@import "~@ng-select/ng-select/themes/default.theme.css";
// ... or 
@import "~@ng-select/ng-select/themes/material.theme.css";

Step 4 (Optional): Configuration

You can also set global configuration and localization messages by providing custom NG_SELECT_DEFAULT_CONFIG

    providers: [
        {
            provide: NG_SELECT_DEFAULT_CONFIG,
            useValue: {
                notFoundText: 'Custom not found'
            }
        }
    ]

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
• Themes
• Items grouping
• Accessibility
• Many more

API

Input	Type	Default	Required	Description
[addTag]	`boolean	((term: string) => any	Promise)`	false
addTagText	string	Add item	no	Set custom text when using tagging
appendTo	string	null	no	Append drodown to body or any other element using css selector
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
[clearable]	boolean	true	no	Allow to clear selected value. Default true
clearAllText	string	Clear all	no	Set custom text for clear all icon title
dropdownPosition	bottom,top,auto	bottom	no	Set the dropdown position on open
[items]	Array<NgOption>	[]	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
[markFirst]	boolean	true	no	Marks first item as focused when opening/filtering. Default true
maxSelectedItems	number	none	no	When multiple = true, allows to set a limit number of selection.
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
[typeahead]	Subject	-	no	Custom autocomplete or filter.
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

Output	Description
(add)	Fired when item is selected
(blur)	Fired on select blur
(change)	Fired on selected value change
(close)	Fired on select dropdown close
(clear)	Fired on clear icon click
(focus)	Fired on select focus
(open)	Fired on select dropdown open
(remove)	Fired when item is removed
(scrollToEnd)	Fired when scrolled to the end of items. Can be used for loading more items in chunks.

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.

Custom styles

If you are not happy with default styles you can easily override them with increased selector specificity. E.g.

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

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

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.

import { Component, ChangeDetectionStrategy, EventEmitter } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs/Observable';
import { catchError, map, debounceTime, switchMap } from 'rxjs/operators';
import { of } from 'rxjs/observable/of';
import { ChangeDetectorRef } from '@angular/core';

@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 = [];
    typeahead = new EventEmitter<string>();

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

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

Custom display templates

This example in Plunkr

To customize look of ng-select you can use ng-template with ng-label-tmp, ng-option-tmp, ng-header-tmp, ng-footer-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-header-tmp>
               Custom header
            </ng-template>
            <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-template ng-footer-tmp>
               Custom footer
            </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;
        });
    }
}

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 having adding this custom css style

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

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

Release

To release to npm just run ./release.sh, of course if you have permissions ;)

Inspiration

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