Gathering detailed insights and metrics for @ng-select/ng-select
Installations
npm install @ng-select/ng-selectDeveloper Guide
BETA
Typescript
No
Module System
ESM
Min. Node Version
>= 18
Node Version
20.18.1
NPM Version
10.8.0
Releases
100
Contributors
129
Languages
6
TypeScript
HTML
SCSS
JavaScript
CSS
Shell
TypeScript (84.29%)
HTML (7.6%)
SCSS (7.47%)
JavaScript (0.4%)
CSS (0.15%)
Shell (0.09%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
Download Statistics
Total Downloads
71,820,983
Last Day
2,148
Last Week
2,148
Last Month
1,174,095
Last Year
17,465,307
GitHub Statistics
3,318 Stars
1,162 Commits
914 Forks
52 Watching
3 Branches
129 Contributors
Bundle Size
88.85 kB
Minified
18.08 kB
Minified + Gzipped
Maintainers
2
Package Meta Information
Latest Version
14.2.0
Package Id
@ng-select/ng-select@14.2.0
Unpacked Size
453.40 kB
Size
78.29 kB
File Count
31
NPM Version
10.8.0
Node Version
20.18.1
Publised On
13 Jan 2025
Total Downloads
Cumulative downloads
Total Downloads
71,820,983
Last day
0%
2,148
Compared to previous day
Last week
-99.1%
2,148
Compared to previous week
Last month
-4.7%
1,174,095
Compared to previous month
Last year
5.6%
17,465,307
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
Peer Dependencies
3
Versions
Angular ng-select - Lightweight all in one UI Select, Multiselect and Autocomplete
See Demo page.
Versions
| Angular | ng-select |
|---|---|
| >=19.0.0 <20.0.0 | v14.x |
| >=18.0.0 <19.0.0 | v13.x |
| >=17.0.0 <18.0.0 | v12.x |
| >=16.0.0 <17.0.0 | v11.x |
| >=15.0.0 <16.0.0 | v10.x |
| >=14.0.0 <15.0.0 | v9.x |
| >=13.0.0 <14.0.0 | v8.x |
| >=12.0.0 <13.0.0 | v7.x |
| >=11.0.0 <12.0.0 | v6.x |
| >=10.0.0 <11.0.0 | v5.x |
| >=9.0.0 <10.0.0 | v4.x |
| >=8.0.0 <9.0.0 | v3.x |
| >=6.0.0 <8.0.0 | v2.x |
| v5.x.x | v1.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:
1Chrome 2 most recent versions 2Firefox latest and extended support release (ESR) 3Edge 2 most recent major versions 4Safari 2 most recent major versions 5iOS 2 most recent major versions 6Android 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
1npm install --save @ng-select/ng-select
YARN
1yarn add @ng-select/ng-select
Step 2:
Standalone: Import NgSelectComponent and other necessary directives directly:
1import { NgLabelTemplateDirective, NgOptionTemplateDirective, NgSelectComponent } from '@ng-select/ng-select'; 2import { FormsModule } from '@angular/forms'; 3 4@Component({ 5 selector: 'example', 6 standalone: true, 7 template: './example.component.html', 8 styleUrl: './example.component.scss', 9 imports: [ 10 NgLabelTemplateDirective, 11 NgOptionTemplateDirective, 12 NgSelectComponent, 13 ], 14}) 15export class ExampleComponent {}
NgModule: Import the NgSelectModule and angular FormsModule module:
1import { NgSelectModule } from '@ng-select/ng-select'; 2import { FormsModule } from '@angular/forms'; 3 4@NgModule({ 5 declarations: [AppComponent], 6 imports: [NgSelectModule, FormsModule], 7 bootstrap: [AppComponent] 8}) 9export 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).
1@import "~@ng-select/ng-select/themes/default.theme.css"; 2// ... or 3@import "~@ng-select/ng-select/themes/material.theme.css"; 4
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.
1 constructor(private config: NgSelectConfig) { 2 this.config.notFoundText = 'Custom not found'; 3 this.config.appendTo = 'body'; 4 // set the bindValue to global config when you use the same 5 // bindValue in most of the place. 6 // You can also override bindValue for the specified template 7 // by defining `bindValue` as property 8 // Eg : <ng-select bindValue="some-new-value"></ng-select> 9 this.config.bindValue = 'value'; 10 }
Usage
Define options in your consuming component:
1@Component({...}) 2export class ExampleComponent { 3 4 selectedCar: number; 5 6 cars = [ 7 { id: 1, name: 'Volvo' }, 8 { id: 2, name: 'Saab' }, 9 { id: 3, name: 'Opel' }, 10 { id: 4, name: 'Audi' }, 11 ]; 12}
In template use ng-select component with your options
1<!--Using ng-option and for loop--> 2<ng-select [(ngModel)]="selectedCar"> 3 @for (car of cars; track car.id) { 4 <ng-option [value]="car.id">{{car.name}}</ng-option> 5 } 6</ng-select> 7 8<!--Using items input--> 9<ng-select [items]="cars" 10 bindLabel="name" 11 bindValue="id" 12 [(ngModel)]="selectedCar"> 13</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:
1map: { 2 '@ng-select/ng-select': 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js', 3}
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 |
| bufferAmount | number | 4 | no | Used in virtual scrolling, the bufferAmount property controls the number of items preloaded in the background to ensure smoother and more seamless scrolling. |
| 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 |
| [fixedPlaceholder] | boolean | false | no | Set placeholder visible even when an item is selected |
| [groupBy] | string | Function | null | no | Allow to group items by key or function expression |
| [groupValue] | (groupKey: string, children: 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 |
| [deselectOnClick] | boolean | false | no | Deselects a selected item when it is clicked in the dropdown. Default false. Default true when multiple is true |
| [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 |
| [preventToggleOnRightClick] | boolean | false | no | Prevent opening of ng-select on right mouse click |
| [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
Ng-select allows to provide custom selection implementation using SELECTION_MODEL_FACTORY. To override default logic provide your factory method in your angular module.
1// app.module.ts 2providers: [ 3 { provide: SELECTION_MODEL_FACTORY, useValue: <SelectionModelFactory>CustomSelectionFactory } 4] 5 6// selection-model.ts 7export function CustomSelectionFactory() { 8 return new CustomSelectionModel(); 9} 10 11export class CustomSelectionModel implements SelectionModel { 12 ... 13}
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:
1this.items.push({id: 1, name: 'New item'})
Component will not detect a change. Instead you need to do:
1this.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.
1<ng-select class="custom"></ng-select>
1.ng-select.custom { 2 border:0px; 3 min-height: 0px; 4 border-radius: 0; 5} 6.ng-select.custom .ng-select-container { 7 min-height: 0px; 8 border-radius: 0; 9}
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.
1.ng-select.custom ::ng-deep .ng-select-container { 2 min-height: 0px; 3 border-radius: 0; 4}
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
1ng-select.ng-invalid.ng-touched .ng-select-container { 2 border-color: #dc3545; 3 box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075), 0 0 0 3px #fde6e8; 4}
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 :)
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
10 commit(s) and 11 issue activity found in the last 90 days -- score normalized to 10
Reason
all changesets reviewed
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:9
Reason
SAST tool is run on all commits
Details
- Info: SAST configuration detected: CodeQL
- Info: all commits (30) are checked with a SAST tool
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/ci.yml:1
- Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1
- Warn: topLevel 'contents' permission set to 'write': .github/workflows/dependabot.yml:5
- Warn: no topLevel permission defined: .github/workflows/release.yml:1
- Warn: no topLevel permission defined: .github/workflows/stale.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/ci.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/ci.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/ci.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/codeql-analysis.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/codeql-analysis.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:52: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/codeql-analysis.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/codeql-analysis.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/dependabot.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/dependabot.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/release.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/release.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:57: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/release.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/stale.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/ng-select/ng-select/stale.yml/master?enable=pin
- Info: 0 out of 9 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 3 third-party GitHubAction dependencies pinned
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
10 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
- Warn: Project is vulnerable to: GHSA-c7qv-q95q-8v27
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
- Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
- Warn: Project is vulnerable to: GHSA-vg6x-rcgg-rjx6
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Score
5.8
/10
Last Scanned on 2025-01-27
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More