- Notifications
You must be signed in to change notification settings - Fork923
⭐ Native angular select component
License
ng-select/ng-select
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
SeeDemo page.
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
| Angular | ng-select |
|---|---|
| >=20.0.0 <21.0.0 | <=15.1.3, >=20.0.1 |
| >=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 |
ng-select supports all browsers supported by Angular. For current list, seehttps://angular.io/guide/browser-support#browser-support. This includes the following specific versions:
Chrome2 most recent versionsFirefoxlatest and extended support release (ESR)Edge2 most recent major versionsSafari2 most recent major versionsiOS2 most recent major versionsAndroid2 most recent major versions- 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
Library is under active development and may have API breaking changes for subsequent major versions after 1.0.0.
npm install --save @ng-select/ng-select
yarn add @ng-select/ng-select
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,],})exportclassExampleComponent{}
import{NgSelectModule}from'@ng-select/ng-select';import{FormsModule}from'@angular/forms';@NgModule({declarations:[AppComponent],imports:[NgSelectModule,FormsModule],bootstrap:[AppComponent]})exportclassAppModule{}
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 yourstyles.scss or include it in.angular-cli.json (Angular v5 and below) orangular.json (Angular v6 onwards).
@import"~@ng-select/ng-select/themes/default.theme.css";// ... or@import"~@ng-select/ng-select/themes/material.theme.css";
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(privateconfig: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';}
Define options in your consuming component:
@Component({...})exportclassExampleComponent{selectedCar:number;cars=[{id:1,name:'Volvo'},{id:2,name:'Saab'},{id:3,name:'Opel'},{id:4,name:'Audi'},];}
In template useng-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 seeDemo page
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 forng-select:
map:{'@ng-select/ng-select':'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js',}
| 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 tooutline 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 positioningbody should haveposition:relative |
| bufferAmount | number | 4 | no | Used in virtual scrolling, thebufferAmount 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. Defaultlabel |
| [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. Defaulttrue |
| [clearOnBackspace] | boolean | true | no | Clear selected values one by one when clicking backspace. Defaulttrue |
| [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. Defaulttrue |
| [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. Defaulttrue. Defaultfalse whencloseOnSelect isfalse |
| [deselectOnClick] | boolean | false | no | Deselects a selected item when it is clicked in the dropdown. Defaultfalse. Defaulttrue whenmultiple istrue |
| [editableSearchTerm] | boolean | false | no | Allow to edit search query if option selected. Defaultfalse. Works only if multiple isfalse. |
| [selectOnTab] | boolean | false | no | Select marked dropdown item using tab. Defaultfalse |
| [tabFocusOnClearButton] | boolean | true | no | Control tab navigation behavior for the clear button. Defaulttrue |
| [openOnEnter] | boolean | true | no | Open dropdown using enter. Defaulttrue |
| [typeahead] | Subject | - | no | Custom autocomplete or advanced filter. |
| [minTermLength] | number | 0 | no | Minimum term length to start a search. Should be used withtypeahead |
| 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 underlyinginput 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 |
| 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. |
| Name | Description |
|---|---|
| open | Opens the select dropdown panel |
| close | Closes the select dropdown panel |
| focus | Focuses the select element |
| blur | Blurs the select element |
| 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. |
Ng-select allows to provide custom selection implementation usingSELECTION_MODEL_FACTORY. To overridedefault logic provide your factory method in your angular module.
// app.module.ts.tsproviders:[{provide:SELECTION_MODEL_FACTORY,useValue:<SelectionModelFactory>CustomSelectionFactory}]// selection-model.tsexportfunctionCustomSelectionFactory(){returnnewCustomSelectionModel();}exportclassCustomSelectionModelimplementsSelectionModel{ ...}
Ng-select component implementsOnPush change detection which means the dirty checking checks for immutabledata 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 thatthis is a pricey operation, however, it is much more performant than runningngDoCheck andconstantly diffing the array.
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 noViewEncapsulation or adding styles to global stylesheet. E.g.
<ng-selectclass="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 usingViewEncapsulation, 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. SeeHere.
By default when you use reactive forms validators or template driven forms validators css classng-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: inset01px1pxrgba(0,0,0,0.075),0003px#fde6e8;}
Contributions are welcome. You can start by looking atissues with labelHelp wanted or creating new Issue with proposal or bug report.Note that we are usinghttps://conventionalcommits.org/ commits format.
Perform theclone-to-launch steps with these terminal commands.
git clone https://github.com/ng-select/ng-selectcd ng-selectyarnyarn run startyarn run testoryarn run test:watchTo release to npm just run./release.sh, of course if you have permissions ;)
This component is inspired byReact select andVirtual scroll. Check theirs amazing work and components :)
About
⭐ Native angular select component
Topics
Resources
License
Contributing
Uh oh!
There was an error while loading.Please reload this page.