0
# Angular ng-select
1

2
Angular ng-select is a comprehensive UI select component library providing single-select, multi-select, and autocomplete functionality with extensive customization options. It supports virtual scrolling for large datasets, custom templates, keyboard navigation, accessibility features, and reactive forms integration.
3

4
## Package Information
5

6
- **Package Name**: @ng-select/ng-select
7
- **Package Type**: npm (Angular library)
8
- **Language**: TypeScript/Angular
9
- **Installation**: `npm install @ng-select/ng-select`
10

11
## Core Imports
12

13
For standalone components:
14

15
```typescript
16
import { NgSelectComponent, NgOptionComponent } from '@ng-select/ng-select';
17
```
18

19
For module-based applications:
20

21
```typescript
22
import { NgSelectModule } from '@ng-select/ng-select';
23
```
24

25
Template directives (standalone):
26

27
```typescript
28
import { 
29
  NgItemLabelDirective, 
30
  NgOptionTemplateDirective, 
31
  NgLabelTemplateDirective 
32
} from '@ng-select/ng-select';
33
```
34

35
Configuration:
36

37
```typescript
38
import { NgSelectConfig } from '@ng-select/ng-select';
39
```
40

41
## Basic Usage
42

43
```typescript
44
import { Component } from '@angular/core';
45
import { NgSelectComponent, NgOptionComponent } from '@ng-select/ng-select';
46

47
@Component({
48
  selector: 'app-example',
49
  standalone: true,
50
  imports: [NgSelectComponent, NgOptionComponent],
51
  template: `
52
    <ng-select 
53
      [(ngModel)]="selectedCity"
54
      placeholder="Select a city"
55
      [clearable]="true"
56
      [searchable]="true">
57
      <ng-option *ngFor="let city of cities" [value]="city.id">
58
        {{ city.name }}
59
      </ng-option>
60
    </ng-select>
61
  `
62
})
63
export class ExampleComponent {
64
  cities = [
65
    {id: 1, name: 'New York'},
66
    {id: 2, name: 'London'},
67
    {id: 3, name: 'Tokyo'}
68
  ];
69
  selectedCity: number | null = null;
70
}
71
```
72

73
For multi-select:
74

75
```typescript
76
@Component({
77
  template: `
78
    <ng-select 
79
      [(ngModel)]="selectedCities"
80
      [multiple]="true"
81
      placeholder="Select cities">
82
      <ng-option *ngFor="let city of cities" [value]="city.id">
83
        {{ city.name }}
84
      </ng-option>
85
    </ng-select>
86
  `
87
})
88
export class MultiSelectComponent {
89
  selectedCities: number[] = [];
90
  cities = [/* ... */];
91
}
92
```
93

94
## Architecture
95

96
Angular ng-select is built around several key components:
97

98
- **Core Components**: `NgSelectComponent` provides the main functionality, `NgOptionComponent` represents individual options, and `NgDropdownPanelComponent` handles the dropdown display
99
- **Template System**: Extensive directive system for customizing every part of the UI including labels, options, headers, footers, and loading states
100
- **Configuration Layer**: Global configuration through `NgSelectConfig` service and per-component configuration through input properties
101
- **Selection Model**: Pluggable selection model system supporting single and multiple selection modes with custom comparison functions
102
- **Virtual Scrolling**: Built-in virtual scrolling support for handling large datasets efficiently
103

104
## Capabilities
105

106
### Core Select Component
107

108
Main select component with comprehensive input/output API supporting all selection modes, customization options, and form integration.
109

110
```typescript { .api }
111
@Component({
112
  selector: 'ng-select',
113
  // ... component implementation
114
})
115
export class NgSelectComponent implements ControlValueAccessor {
116
  // Core selection properties
117
  @Input() items: any[];
118
  @Input() bindLabel: string;
119
  @Input() bindValue: string;
120
  @Input() multiple: boolean;
121
  @Input() placeholder: string;
122
  @Input() disabled: boolean;
123
  @Input() readonly: boolean;
124
  
125
  // Display and interaction properties
126
  @Input() clearable: boolean;
127
  @Input() searchable: boolean;
128
  @Input() loading: boolean;
129
  @Input() virtualScroll: boolean;
130
  @Input() closeOnSelect: boolean;
131
  @Input() hideSelected: boolean;
132
  
133
  // Customization properties
134
  @Input() appearance: string;
135
  @Input() dropdownPosition: DropdownPosition;
136
  @Input() appendTo: string;
137
  @Input() maxSelectedItems: number;
138
  
139
  // Events
140
  @Output() change: EventEmitter<any>;
141
  @Output() open: EventEmitter<void>;
142
  @Output() close: EventEmitter<void>;
143
  @Output() focus: EventEmitter<void>;
144
  @Output() blur: EventEmitter<void>;
145
  @Output() search: EventEmitter<{term: string, items: any[]}>;
146
  @Output() clear: EventEmitter<void>;
147
  @Output() add: EventEmitter<any>;
148
  @Output() remove: EventEmitter<any>;
149
  @Output() scroll: EventEmitter<{start: number, end: number}>;
150
  @Output() scrollToEnd: EventEmitter<void>;
151
}
152
```
153

154
[Core Select Component](./ng-select-component.md)
155

156
### Template Customization
157

158
Comprehensive template directive system for customizing every aspect of the select component's appearance and behavior.
159

160
```typescript { .api }
161
// Item display templates
162
@Directive({ selector: '[ng-option-tmp]' })
163
export class NgOptionTemplateDirective {}
164

165
@Directive({ selector: '[ng-label-tmp]' })
166
export class NgLabelTemplateDirective {}
167

168
@Directive({ selector: '[ng-multi-label-tmp]' })
169
export class NgMultiLabelTemplateDirective {}
170

171
// Layout templates
172
@Directive({ selector: '[ng-header-tmp]' })
173
export class NgHeaderTemplateDirective {}
174

175
@Directive({ selector: '[ng-footer-tmp]' })
176
export class NgFooterTemplateDirective {}
177

178
// State templates
179
@Directive({ selector: '[ng-notfound-tmp]' })
180
export class NgNotFoundTemplateDirective {}
181

182
@Directive({ selector: '[ng-loadingtext-tmp]' })
183
export class NgLoadingTextTemplateDirective {}
184
```
185

186
[Template Customization](./template-directives.md)
187

188
### Configuration and Services
189

190
Global configuration service and utility services for customizing default behavior and accessing internal functionality.
191

192
```typescript { .api }
193
@Injectable()
194
export class NgSelectConfig {
195
  placeholder: string;
196
  notFoundText: string;
197
  typeToSearchText: string;
198
  addTagText: string;
199
  loadingText: string;
200
  clearAllText: string;
201
  disableVirtualScroll: boolean;
202
  openOnEnter: boolean;
203
  appendTo: string;
204
  bindValue: string;
205
  bindLabel: string;
206
  // ... additional configuration properties
207
}
208

209
@Injectable()
210
export class NgDropdownPanelService {
211
  dimensions: PanelDimensions;
212
  calculateItems(scrollPos: number, itemsLength: number, buffer: number): ItemsRangeResult;
213
}
214
```
215

216
[Configuration and Services](./configuration-services.md)
217

218
### Option Highlighting
219

220
Directive for highlighting search terms within option text, perfect for autocomplete and search scenarios.
221

222
```typescript { .api }
223
@Directive({
224
  selector: '[ngOptionHighlight]'
225
})
226
export class NgOptionHighlightDirective {
227
  @Input('ngOptionHighlight') term: string;
228
}
229
```
230

231
[Option Highlighting](./ng-option-highlight.md)
232

233
### Types and Interfaces
234

235
Complete type definitions for all interfaces, enums, and function types used throughout the library.
236

237
```typescript { .api }
238
interface NgOption {
239
  [name: string]: any;
240
  index?: number;
241
  htmlId?: string;
242
  selected?: boolean;
243
  disabled?: boolean;
244
  marked?: boolean;
245
  label?: string;
246
  value?: string | any;
247
  parent?: NgOption;
248
  children?: NgOption[];
249
}
250

251
type DropdownPosition = 'top' | 'right' | 'bottom' | 'left' | 'auto';
252

253
enum KeyCode {
254
  Tab = 'Tab',
255
  Enter = 'Enter',
256
  Esc = 'Escape',
257
  Space = ' ',
258
  ArrowUp = 'ArrowUp',
259
  ArrowDown = 'ArrowDown',
260
  Backspace = 'Backspace'
261
}
262

263
type AddTagFn = (term: string) => any | Promise<any>;
264
type CompareWithFn = (a: any, b: any) => boolean;
265
type GroupValueFn = (key: string | any, children: any[]) => string | any;
266
```
267

268
[Types and Interfaces](./types-interfaces.md)