select angular package

[](https://badge.fury.io/js/%40ng-select%2Fng-select) [![Coverage Status][coveralls-image]][coveralls-url] [][ng-select-url] [coveralls-image]: https://coveralls.io/repos/github/ng-select/ng-select/badge.svg?branch=master [coveralls-url]: https://coveralls.io/github/ng-select/ng-select?branch=master [ng-select-url]: https://unpkg.com/@ng-select/ng-select@latest # Angular ng-select - Lightweight all in one UI Select, Multiselect and Autocomplete See [Demo](https://ng-select.github.io/ng-select) page. --- ## Versions | Angular| ng-select| | ------|:------:| | >=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 | --- perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons. Table of contents ================= * [Features](#features) * [Getting started](#getting-started) * [API](#api) * [Change detection](#change-detection) * [Custom styles](#custom-styles) * [Validation state](#validation-state) * [Contributing](#contributing) * [Development](#development) * [Inspiration](#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 ```shell npm install --save @ng-select/ng-select ``` #### YARN ```shell yarn add @ng-select/ng-select ``` ### Step 2: Import the NgSelectModule and angular FormsModule module: ```js 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). ```scss @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. ```js 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'; } ``` ### 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`: ```js map: { '@ng-select/ng-select': 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js', } ``` ## 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` | | 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 | | [groupBy] | `string` \| `Function` | null | no | Allow to group items by key or function expression | | [groupValue] | `(groupKey: string, cildren: 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` | | [editableSearchTerm] | `boolean` | `false` | no | Allow to edit search query if option selected. Default `fa