13.8.1 • Published 13 days ago

@ng-select/ng-select v13.8.1

Weekly downloads
199,729
License
MIT
Repository
github
Last release
13 days ago

npm version Coverage Status gzip bundle size ng-select channel on discord

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

See Demo page.


Versions

Angularng-select
>=18.0.0 <19.0.0v13.x
>=17.0.0 <18.0.0v12.x
>=16.0.0 <17.0.0v11.x
>=15.0.0 <16.0.0v10.x
>=14.0.0 <15.0.0v9.x
>=13.0.0 <14.0.0v8.x
>=12.0.0 <13.0.0v7.x
>=11.0.0 <12.0.0v6.x
>=10.0.0 <11.0.0v5.x
>=9.0.0 <10.0.0v4.x
>=8.0.0 <9.0.0v3.x
>=6.0.0 <8.0.0v2.x
v5.x.xv1.x

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

  • 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

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

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

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

<!--Using items input-->
<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

InputTypeDefaultRequiredDescription
addTagboolean \| ((term: string) => any \| Promise<any>)falsenoAllows to create custom options.
addTagTextstringAdd itemnoSet custom text when using tagging
appearancestringunderlinenoAllows to select dropdown appearance. Set to outline to add border instead of underline (applies only to Material theme)
appendTostringnullnoAppend dropdown to body or any other element using css selector. For correct positioning body should have position:relative
bufferAmountstringnullnoAppend dropdown to body or any other element using css selector. For correct positioning body should have position:relative
bindValuestring-noObject property to use for selected model. By default binds to whole object.
bindLabelstringlabelnoObject property to use for label. Default label
closeOnSelectbooleantruenoWhether to close the menu when a value is selected
clearAllTextstringClear allnoSet custom text for clear all icon title
clearablebooleantruenoAllow to clear selected value. Default true
clearOnBackspacebooleantruenoClear selected values one by one when clicking backspace. Default true
compareWith(a: any, b: any) => boolean(a, b) => a === bnoA 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.
dropdownPositionbottom | top | autoautonoSet the dropdown position on open
fixedPlaceholderbooleanfalsenoSet placeholder visible even when an item is selected
groupBystring | FunctionnullnoAllow to group items by key or function expression
groupValue(groupKey: string, children: any[]) => Object-noFunction expression to provide group value
selectableGroupbooleanfalsenoAllow to select group when groupBy is used
selectableGroupAsModelbooleantruenoIndicates whether to select all children or group itself
itemsArray<any>[]yesItems array
loadingboolean-noYou can set the loading state from the outside (e.g. async items loading)
loadingTextstringLoading...noSet custom text when for loading items
labelForIdstring-noId to associate control with label.
markFirstbooleantruenoMarks first item as focused when opening/filtering.
isOpenboolean-noAllows manual control of dropdown opening and closing. true - won't close. false - won't open.
maxSelectedItemsnumbernonenoWhen multiple = true, allows to set a limit number of selection.
hideSelectedbooleanfalsenoAllows to hide selected items.
multiplebooleanfalsenoAllows to select multiple items.
notFoundTextstringNo items foundnoSet custom text when filter returns empty result
placeholderstring-noPlaceholder text.
searchablebooleantruenoAllow to search for value. Default true
readonlybooleanfalsenoSet ng-select as readonly. Mostly used with reactive forms.
searchFn(term: string, item: any) => booleannullnoAllow to filter by custom search function
searchWhileComposingbooleantruenoWhether items should be filtered while composition started
trackByFn(item: any) => anynullnoProvide custom trackBy function
clearSearchOnAddbooleantruenoClears search input when item is selected. Default true. Default false when closeOnSelect is false
deselectOnClickbooleanfalsenoDeselects a selected item when it is clicked in the dropdown. Default false. Default true when multiple is true
editableSearchTermbooleanfalsenoAllow to edit search query if option selected. Default false. Works only if multiple is false.
selectOnTabbooleanfalsenoSelect marked dropdown item using tab. Default false
openOnEnterbooleantruenoOpen dropdown using enter. Default true
typeaheadSubject-noCustom autocomplete or advanced filter.
minTermLengthnumber0noMinimum term length to start a search. Should be used with typeahead
typeToSearchTextstringType to searchnoSet custom text when using Typeahead
virtualScrollbooleanfalsenoEnable virtual scroll for better performance when rendering a lot of data
inputAttrs{ [key: string]: string }-noPass custom attributes to underlying input element
tabIndexnumber-noSet tabindex on ng-select
preventToggleOnRightClickbooleanfalsenoPrevent opening of ng-select on right mouse click
keyDownFn($event: KeyboardEvent) => booltruenoProvide custom keyDown function. Executed before default handler. Return false to suppress execution of default key down handlers

Outputs

OutputDescription
(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

NameDescription
openOpens the select dropdown panel
closeCloses the select dropdown panel
focusFocuses the select element
blurBlurs the select element

Other

NameTypeDescription
ngOptionHighlightdirectiveHighlights search term in option. Accepts search term. Should be used on option element. README
NgSelectConfigconfigurationConfiguration provider for the NgSelect component. You can inject this service and provide application wide configuration.
SELECTION_MODEL_FACTORYserviceDI token for SelectionModel implementation. You can provide custom implementation changing selection behaviour.

Custom selection logic

Ng-select 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

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 = [...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;
}

WARNING: Keep in mind that ng-deep is deprecated and there is no alternative to it yet. See Here.

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

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 Virtual scroll. Check theirs amazing work and components :)

@arunkeshavareddy/dc-common@ljmarquezge2y/worldpay-spartacus@hivecloud/angular-ui-libcustomermanagementsaeculum-angular-component-librarysaeculum-formlycb-customermagementcb-masterservicecb-masterservice1cb-msdocument-center-ang290778-123laji-frontcz-controlsvideo-visit-librarypulsifi-lib@zdavy4k/headerelements-reactive-formangular-erfapp14-vivesintabaco-serverbee-common-workspaceabp-zero-templates-gabp-zero-template-gmanualabp-zero-templat-gabp-zero-template-gcase-corevn-workspaceoscar-ui-angularkup.common.utilangularcommonlibterersupport-request-librarynaologic-design@careercruising/panda-ui@gomoko/admin-uigoil-alerts-testpc.ui.shared1pc.ui.shared2joymo-ui@cubez-it/ticketsgo-uingpacab-shared-imi-v124lib-form-fieldsngx-moment-timezone-pickerpaymentop@sm-soluciones/core-app@infinitebrahmanuniverse/nolb-_ng-@bytebean/admin-uiheader-footerigtb-nab-escrow-common-modulesui-fifth-third-shared-modulekruzer-ui@everything-registry/sub-chunk-647fiscalia-libreriashenriquegdin-uiisapre-digitalabp-zero-template-resaaaaclinical-notingcommercial-cockpit-uicodeshellcomponents-lib-npmcombo-datacopyl-project-selectcsi-service-gateway-libcumulocity-datapoints-charting-widgetcui-controlscui-controls-testdatafunc-controls-bootstrapcxliveevaluate-spaessence-light-sabereditor360-angular-wrapper-projecteris-formseris-forms2engage-libequipment-componentsfclouddzeus-app-updatefrequence-component-libfqtablegrantsconnect-frontendgdx-angular-uifst-ngx-view-index-rdsfsp-supporth21-be-ui-kith21-mapdc-commonintellect-liquidity-modulepom-gestion-humana-siproc-vis-webpreview-lib-appparticipant-design-systempf_styleguideoversetterpsp-uifinos-dynamic-formunwork-builder-15@erengee/extensions@libriciel/ls-workflowkolay-elementslibreria-saimyrli3-widgets
13.7.2

14 days ago

13.8.0

14 days ago

13.8.1

13 days ago

13.7.1

28 days ago

13.3.0

3 months ago

13.4.2

2 months ago

13.4.0

3 months ago

13.4.1

3 months ago

13.1.1

4 months ago

13.1.0

4 months ago

13.2.0

4 months ago

13.2.1

3 months ago

13.7.0

2 months ago

13.0.4

4 months ago

13.0.2

4 months ago

13.0.3

4 months ago

13.0.0

4 months ago

13.0.1

4 months ago

13.5.1

2 months ago

13.5.2

2 months ago

13.5.0

2 months ago

13.6.0

2 months ago

12.0.7

8 months ago

12.0.5

9 months ago

12.0.6

9 months ago

12.0.3

11 months ago

12.0.4

11 months ago

12.0.0

11 months ago

12.0.1

11 months ago

12.0.2

11 months ago

11.2.0

12 months ago

11.1.1

1 year ago

11.1.2

12 months ago

11.1.0

1 year ago

11.0.0

1 year ago

10.0.4

2 years ago

10.0.2

2 years ago

10.0.3

2 years ago

9.0.3

2 years ago

10.0.0

2 years ago

10.0.1

2 years ago

9.1.0

2 years ago

9.0.2

2 years ago

8.2.0

2 years ago

9.0.1

2 years ago

9.0.0

2 years ago

8.3.0

2 years ago

8.1.0

3 years ago

8.1.1

3 years ago

8.0.0

3 years ago

7.4.0

3 years ago

7.3.0

3 years ago

7.2.0

3 years ago

7.1.1

3 years ago

7.1.0

3 years ago

7.0.1

3 years ago

7.0.0

3 years ago

6.1.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.15

4 years ago

5.0.14

4 years ago

5.0.13

4 years ago

5.0.12

4 years ago

5.0.10

4 years ago

5.0.11

4 years ago

5.0.9

4 years ago

5.0.8

4 years ago

5.0.7

4 years ago

5.0.6

4 years ago

5.0.5

4 years ago

5.0.4

4 years ago

5.0.3

4 years ago

5.0.2

4 years ago

5.0.1

4 years ago

5.0.0

4 years ago

4.0.4

4 years ago

4.0.3

4 years ago

4.0.2

4 years ago

4.0.1

4 years ago

4.0.0

5 years ago

3.7.3

5 years ago

3.7.2

5 years ago

3.7.1

5 years ago

3.7.0

5 years ago

3.6.2

5 years ago

3.6.1

5 years ago

3.6.0

5 years ago

3.5.0

5 years ago

3.4.0

5 years ago

3.3.0

5 years ago

3.2.0

5 years ago

3.1.1

5 years ago

3.1.0

5 years ago

3.0.7

5 years ago

3.0.6

5 years ago

3.0.5

5 years ago

3.0.4

5 years ago

3.0.3

5 years ago

3.0.2

5 years ago

3.0.1

5 years ago

3.0.0

5 years ago

2.20.5

5 years ago

2.20.4

5 years ago

2.20.3

5 years ago

2.20.2

5 years ago

2.20.1

5 years ago

2.20.0

5 years ago

2.19.0

5 years ago

2.18.0

5 years ago

2.17.0

5 years ago

2.16.4

6 years ago

2.16.3

6 years ago

2.16.2

6 years ago

2.16.1

6 years ago

2.16.0

6 years ago

2.15.3

6 years ago

2.15.2

6 years ago

2.15.1

6 years ago

2.15.0

6 years ago

2.14.0

6 years ago

2.13.3

6 years ago

2.13.2

6 years ago

2.13.1

6 years ago

2.13.0

6 years ago

2.12.1

6 years ago

1.6.3

6 years ago

2.12.0

6 years ago

2.11.2

6 years ago

2.11.1

6 years ago

2.11.0

6 years ago

2.10.5

6 years ago

2.10.4

6 years ago

2.10.3

6 years ago

2.10.2

6 years ago

2.10.1

6 years ago

2.10.0

6 years ago

1.6.2

6 years ago

2.9.1

6 years ago

2.9.0

6 years ago

1.6.1

6 years ago

2.8.1

6 years ago

2.8.0

6 years ago

2.7.1

6 years ago

2.7.0

6 years ago

2.6.0

6 years ago

2.5.1

6 years ago

1.6.0

6 years ago

2.5.0

6 years ago

2.4.3

6 years ago

2.4.2

6 years ago

2.4.1

6 years ago

2.4.0

6 years ago

2.3.6

6 years ago

2.3.5

6 years ago

2.3.3

6 years ago

2.3.2

6 years ago

2.3.1

6 years ago

2.3.0

6 years ago

2.2.0

6 years ago

2.1.3

6 years ago

2.1.2

6 years ago

2.1.1

6 years ago

2.1.0

6 years ago

1.5.2

6 years ago

2.0.3

6 years ago

1.5.1

6 years ago

2.0.2

6 years ago

1.5.0

6 years ago

2.0.1

6 years ago

2.0.0

6 years ago

1.4.2

6 years ago

1.4.1

6 years ago

1.4.0

6 years ago

1.3.0

6 years ago

1.2.1

6 years ago

1.2.0

6 years ago

1.1.4

6 years ago

1.1.3

6 years ago

1.1.2

6 years ago

1.1.1

6 years ago

1.1.0

6 years ago

1.0.6

6 years ago

1.0.5

6 years ago

1.0.4

6 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1-rc.0

6 years ago

0.36.2

6 years ago

0.36.1

6 years ago

0.36.0

6 years ago

0.35.2

6 years ago

0.35.1

6 years ago

0.35.0

7 years ago

0.34.3

7 years ago

0.34.2

7 years ago

0.34.1

7 years ago

0.34.0

7 years ago

0.33.0

7 years ago

0.32.0

7 years ago

0.31.1

7 years ago

0.31.0

7 years ago

0.30.1

7 years ago

0.30.0

7 years ago

0.29.1

7 years ago

0.29.0

7 years ago

0.28.1

7 years ago

0.28.0

7 years ago

0.27.1

7 years ago

0.27.0

7 years ago

0.26.2

7 years ago

0.26.1

7 years ago

0.26.0

7 years ago

0.25.0

7 years ago

0.24.1

7 years ago

0.24.0

7 years ago

0.23.3

7 years ago

0.23.2

7 years ago

0.23.1

7 years ago

0.23.0

7 years ago

0.22.0

7 years ago

0.21.0

7 years ago

0.20.4

7 years ago

0.20.3

7 years ago

0.20.2

7 years ago

0.20.1

7 years ago

0.20.0

7 years ago

0.19.0

7 years ago

0.18.0

7 years ago

0.17.2

7 years ago

0.17.1

7 years ago

0.17.0

7 years ago

0.16.0

7 years ago

0.15.2

7 years ago

0.15.1

7 years ago

0.15.0

7 years ago

0.14.4

7 years ago

0.14.3

7 years ago

0.14.2

7 years ago

0.14.1

7 years ago

0.14.0

7 years ago

0.13.0

7 years ago

0.12.0

7 years ago

0.11.0

7 years ago

0.10.0

7 years ago

0.9.0

7 years ago

0.8.0

7 years ago

0.7.1

7 years ago

0.7.0

7 years ago

0.6.2

7 years ago

0.6.1

7 years ago

0.6.0

7 years ago

0.5.0

7 years ago

0.4.5

7 years ago

0.4.4

7 years ago

0.4.3

7 years ago

0.4.2

7 years ago

0.4.1

7 years ago

0.4.0

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.5

7 years ago

0.2.4

7 years ago

0.2.3

7 years ago

0.2.2

7 years ago

0.2.1

7 years ago

0.2.0

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago

0.0.5

7 years ago

0.0.4

7 years ago

0.0.3

7 years ago

0.0.2

7 years ago

0.0.2-alpha

7 years ago

0.0.0-1

7 years ago