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

See Demo page.

Versions

Warning: Do not use versions 15.2.0, 16.0.0, 17.0.0, 18.0.0, 19.0.0, 20.0.0 as they contain unresolved issues

Browser Support

ng-select supports all browsers supported by Angular. For current list, see https://angular.io/guide/browser-support#browser-support. This includes the following specific versions:

Chrome  2 most recent versions
Firefox latest and extended support release (ESR)
Edge    2 most recent major versions
Safari  2 most recent major versions
iOS 2 most recent major versions
Android 2 most recent major versions

Table of contents

• Features
• Getting started
• API
• Change detection
• Custom styles
• Validation state
• Contributing
• Development
• Inspiration

Features

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

Warning

Library is under active development and may have API breaking changes for 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

PNPM

pnpm add @ng-select/ng-select

Step 2:

Standalone: Import NgSelectComponent and other necessary directives directly:

import { NgLabelTemplateDirective, NgOptionTemplateDirective, NgSelectComponent } from '@ng-select/ng-select';
import { FormsModule } from '@angular/forms';

@Component({
    selector: 'example',
    standalone: true,
    template: './example.component.html',
    styleUrl: './example.component.scss',
    imports: [NgLabelTemplateDirective, NgOptionTemplateDirective, NgSelectComponent],
})
export class ExampleComponent {}

NgModule: Import the NgSelectModule and angular FormsModule module:

import { NgSelectModule } from '@ng-select/ng-select';
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, 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 (Angular v5 and below) or angular.json (Angular v6 onwards).

@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 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';
  }

Usage

Define options in your consuming component:

@Component({...})
export class ExampleComponent {

    selectedCar: number;

    cars = [
        { id: 1, name: 'Volvo' },
        { id: 2, name: 'Saab' },
        { id: 3, name: 'Opel' },
        { id: 4, name: 'Audi' },
    ];
}

In template use ng-select component with your options

<ng-select [(ngModel)]="selectedCar">
    @for (car of cars; track car.id) {
    <ng-option [value]="car.id">{{car.name}}</ng-option>
    }
</ng-select>


<ng-select [items]="cars" bindLabel="name" bindValue="id" [(ngModel)]="selectedCar"> </ng-select>

For more detailed examples see Demo page

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',
}

API

Inputs