0
# Types and Interfaces
1

2
Complete type definitions for all interfaces, enums, and function types used throughout the Angular ng-select library. These types provide full TypeScript support and enable type-safe development.
3

4
## Capabilities
5

6
### Core Data Types
7

8
Fundamental types representing options, selections, and data structures.
9

10
```typescript { .api }
11
/**
12
 * Interface representing an option item in the select component
13
 * Can be extended with custom properties as needed
14
 */
15
interface NgOption {
16
  /** Allow any additional custom properties */
17
  [name: string]: any;
18
  /** Internal index of the option */
19
  index?: number;
20
  /** Unique HTML ID for accessibility */
21
  htmlId?: string;
22
  /** Whether this option is currently selected */
23
  selected?: boolean;
24
  /** Whether this option is disabled and cannot be selected */
25
  disabled?: boolean;
26
  /** Whether this option is currently marked/highlighted */
27
  marked?: boolean;
28
  /** Display label for the option */
29
  label?: string;
30
  /** Value of the option (can be any type) */
31
  value?: any;
32
  /** Parent option for grouped options */
33
  parent?: NgOption;
34
  /** Child options for group headers */
35
  children?: NgOption[];
36
}
37

38
/**
39
 * Union type for dropdown positioning options
40
 * Determines where the dropdown panel appears relative to the select input
41
 */
42
type DropdownPosition = 'top' | 'right' | 'bottom' | 'left' | 'auto';
43

44
/**
45
 * Enhanced dropdown position type with additional positioning control
46
 */
47
interface DropdownPositionOptions {
48
  /** Primary position preference */
49
  position: DropdownPosition;
50
  /** Whether to flip position if there's insufficient space */
51
  autoFlip?: boolean;
52
  /** Custom offset from the select input */
53
  offset?: {x: number, y: number};
54
}
55
```
56

57
### Function Types
58

59
Type definitions for callback functions and customization hooks.
60

61
```typescript { .api }
62
/**
63
 * Function type for adding custom tags/items to the selection
64
 * Used when addTag property is set to a function
65
 */
66
type AddTagFn = (term: string) => any | Promise<any>;
67

68
/**
69
 * Function type for comparing items to determine equality
70
 * Used for tracking selections and preventing duplicates
71
 */
72
type CompareWithFn = (a: any, b: any) => boolean;
73

74
/**
75
 * Function type for custom search/filter logic
76
 * Return true if item matches the search term
77
 */
78
type SearchFn = (term: string, item: any) => boolean;
79

80
/**
81
 * Function type for generating group values from grouped items
82
 * Used when groupBy is set and custom group processing is needed
83
 */
84
type GroupValueFn = (key: string | any, children: any[]) => string | any;
85

86
/**
87
 * Function type for custom keyboard event handling
88
 * Return true to prevent default behavior
89
 */
90
type KeyDownFn = (event: KeyboardEvent) => boolean;
91

92
/**
93
 * Function type for trackBy optimization in large lists
94
 * Should return unique identifier for each item
95
 */
96
type TrackByFn = (index: number, item: any) => any;
97

98
/**
99
 * Function type for custom item loading/fetching
100
 * Used with typeahead functionality for remote data
101
 */
102
type LoadItemsFn = (term: string) => Observable<any[]> | Promise<any[]> | any[];
103

104
/**
105
 * Function type for custom clear confirmation
106
 * Return true to proceed with clear, false to cancel
107
 */
108
type ClearConfirmFn = (items: any[]) => boolean | Promise<boolean>;
109
```
110

111
### Event Types
112

113
Type definitions for event payloads and event-related interfaces.
114

115
```typescript { .api }
116
/**
117
 * Event payload for search events
118
 * Contains current search term and filtered items
119
 */
120
interface SearchEvent {
121
  /** Current search/filter term */
122
  term: string;
123
  /** Items matching the current search term */
124
  items: any[];
125
}
126

127
/**
128
 * Event payload for scroll events during virtual scrolling
129
 * Contains information about currently visible range
130
 */
131
interface ScrollEvent {
132
  /** Starting index of visible items */
133
  start: number;
134
  /** Ending index of visible items */
135
  end: number;
136
}
137

138
/**
139
 * Event payload for change events
140
 * Contains previous and current values
141
 */
142
interface ChangeEvent {
143
  /** Previously selected value(s) */
144
  previousValue: any;
145
  /** Currently selected value(s) */
146
  currentValue: any;
147
  /** Whether the change was triggered by user action */
148
  isUserInput: boolean;
149
}
150

151
/**
152
 * Event payload for add/remove events
153
 * Contains information about the item being added or removed
154
 */
155
interface ItemEvent {
156
  /** The item being added or removed */
157
  item: any;
158
  /** Index of the item in the items array */
159
  index: number;
160
  /** Whether this was triggered by user action */
161
  isUserInput: boolean;
162
}
163

164
/**
165
 * Event payload for focus/blur events
166
 * Contains event details and current component state
167
 */
168
interface FocusEvent {
169
  /** The original DOM event */
170
  event: Event;
171
  /** Current selected value(s) */
172
  value: any;
173
  /** Whether component has valid selection */
174
  hasValue: boolean;
175
}
176
```
177

178
### Keyboard Navigation
179

180
Enum and types for keyboard interaction handling.
181

182
```typescript { .api }
183
/**
184
 * Enum defining keyboard key codes used for navigation
185
 * Follows modern KeyboardEvent.key standard
186
 */
187
enum KeyCode {
188
  Tab = 'Tab',
189
  Enter = 'Enter',
190
  Esc = 'Escape',
191
  Space = ' ',
192
  ArrowUp = 'ArrowUp',
193
  ArrowDown = 'ArrowDown',
194
  Backspace = 'Backspace'
195
}
196

197
/**
198
 * Interface for keyboard navigation configuration
199
 */
200
interface KeyboardConfig {
201
  /** Keys that open the dropdown */
202
  openKeys: KeyCode[];
203
  /** Keys that close the dropdown */
204
  closeKeys: KeyCode[];
205
  /** Keys that navigate up in the list */
206
  upKeys: KeyCode[];
207
  /** Keys that navigate down in the list */
208
  downKeys: KeyCode[];
209
  /** Keys that select the current item */
210
  selectKeys: KeyCode[];
211
  /** Keys that clear the selection */
212
  clearKeys: KeyCode[];
213
  /** Whether to prevent default browser behavior */
214
  preventDefault: boolean;
215
}
216
```
217

218
### Virtual Scrolling Types
219

220
Types for virtual scrolling functionality and performance optimization.
221

222
```typescript { .api }
223
/**
224
 * Interface for panel dimension calculations used in virtual scrolling
225
 */
226
interface PanelDimensions {
227
  /** Height of individual items in pixels */
228
  itemHeight: number;
229
  /** Total height of the scrollable panel */
230
  panelHeight: number;
231
  /** Number of items that fit in the visible viewport */
232
  itemsPerViewport: number;
233
  /** Additional buffer items to render outside viewport */
234
  bufferSize: number;
235
}
236

237
/**
238
 * Interface for virtual scroll calculation results
239
 * Used by NgDropdownPanelService for performance optimization
240
 */
241
interface ItemsRangeResult {
242
  /** Total height needed for scrollbar calculation */
243
  scrollHeight: number;
244
  /** Top padding to maintain correct scroll position */
245
  topPadding: number;
246
  /** Bottom padding for proper scrollbar sizing */
247
  bottomPadding: number;
248
  /** Start index of items to render */
249
  start: number;
250
  /** End index of items to render */
251
  end: number;
252
  /** Total number of items being virtualized */
253
  totalItems: number;
254
}
255

256
/**
257
 * Configuration interface for virtual scrolling behavior
258
 */
259
interface VirtualScrollConfig {
260
  /** Enable virtual scrolling */
261
  enabled: boolean;
262
  /** Number of items to render outside visible area */
263
  bufferAmount: number;
264
  /** Minimum number of items before virtual scroll activates */
265
  threshold: number;
266
  /** Fixed height for all items (improves performance) */
267
  itemHeight?: number;
268
  /** Dynamic height calculation function */
269
  itemHeightFn?: (item: any, index: number) => number;
270
}
271
```
272

273
### Selection Model Types
274

275
Types for the pluggable selection model system.
276

277
```typescript { .api }
278
/**
279
 * Interface defining the contract for selection model implementations
280
 * Allows for custom selection behavior and state management
281
 */
282
interface SelectionModel {
283
  /** Array of currently selected options */
284
  value: NgOption[];
285
  
286
  /**
287
   * Select an item and update the model
288
   */
289
  select(item: NgOption, multiple: boolean, selectableGroupAsModel: boolean): void;
290
  
291
  /**
292
   * Unselect an item and update the model
293
   */
294
  unselect(item: NgOption, multiple: boolean): void;
295
  
296
  /**
297
   * Clear all selections with optional disabled item preservation
298
   */
299
  clear(keepDisabled: boolean): void;
300
  
301
  /**
302
   * Check if an item is currently selected
303
   */
304
  isSelected(item: NgOption): boolean;
305
  
306
  /**
307
   * Get all selected values (not NgOption objects)
308
   */
309
  getSelectedValues(): any[];
310
}
311

312
/**
313
 * Factory function type for creating selection model instances
314
 */
315
type SelectionModelFactory = () => SelectionModel;
316

317
/**
318
 * Configuration interface for selection behavior
319
 */
320
interface SelectionConfig {
321
  /** Maximum number of items that can be selected */
322
  maxItems?: number;
323
  /** Minimum number of items that must be selected */
324
  minItems?: number;
325
  /** Custom validation function for selections */
326
  validator?: (selectedItems: any[]) => boolean;
327
  /** Whether to automatically clear invalid selections */
328
  autoClearInvalid: boolean;
329
}
330
```
331

332
### Styling and Theming Types
333

334
Types for customizing appearance and theming.
335

336
```typescript { .api }
337
/**
338
 * Union type for built-in appearance options
339
 */
340
type AppearanceType = 'default' | 'material' | 'bootstrap' | 'outline' | 'minimal';
341

342
/**
343
 * Interface for theme customization
344
 */
345
interface ThemeConfig {
346
  /** Name of the theme */
347
  name: string;
348
  /** CSS class names for different component states */
349
  classes: {
350
    container: string;
351
    single: string;
352
    multiple: string;
353
    dropdown: string;
354
    option: string;
355
    optionSelected: string;
356
    optionDisabled: string;
357
    optionMarked: string;
358
    label: string;
359
    clear: string;
360
    arrow: string;
361
    loading: string;
362
  };
363
  /** Custom CSS properties for theme variables */
364
  properties?: {[key: string]: string};
365
}
366

367
/**
368
 * Configuration for custom styling
369
 */
370
interface StyleConfig {
371
  /** Custom CSS classes to apply */
372
  classes?: {[key: string]: string};
373
  /** Inline styles to apply */
374
  styles?: {[key: string]: string};
375
  /** Theme configuration */
376
  theme?: ThemeConfig;
377
}
378
```
379

380
### Validation Types
381

382
Types for form validation and error handling.
383

384
```typescript { .api }
385
/**
386
 * Interface for validation result information
387
 */
388
interface ValidationResult {
389
  /** Whether the current value is valid */
390
  isValid: boolean;
391
  /** Array of validation error messages */
392
  errors: string[];
393
  /** Validation metadata */
394
  metadata?: {[key: string]: any};
395
}
396

397
/**
398
 * Function type for custom validation logic
399
 */
400
type ValidatorFn = (value: any) => ValidationResult | null;
401

402
/**
403
 * Interface for validation configuration
404
 */
405
interface ValidationConfig {
406
  /** Array of validator functions to apply */
407
  validators: ValidatorFn[];
408
  /** Whether to validate on value change */
409
  validateOnChange: boolean;
410
  /** Whether to validate on blur */
411
  validateOnBlur: boolean;
412
  /** Custom error message formatter */
413
  errorFormatter?: (errors: string[]) => string;
414
}
415
```
416

417
### Integration Types
418

419
Types for integration with external libraries and frameworks.
420

421
```typescript { .api }
422
/**
423
 * Interface for reactive forms integration
424
 */
425
interface ReactiveFormsIntegration {
426
  /** Form control instance */
427
  control: AbstractControl;
428
  /** Validation state */
429
  validationState: ValidationResult;
430
  /** Touch state */
431
  touched: boolean;
432
  /** Dirty state */
433
  dirty: boolean;
434
}
435

436
/**
437
 * Interface for Observable/RxJS integration
438
 */
439
interface ObservableIntegration {
440
  /** Observable for item loading */
441
  items$: Observable<any[]>;
442
  /** Observable for search term changes */
443
  searchTerm$: Observable<string>;
444
  /** Observable for selection changes */
445
  selection$: Observable<any>;
446
  /** Loading state observable */
447
  loading$: Observable<boolean>;
448
}
449

450
/**
451
 * Type for async data loading patterns
452
 */
453
type AsyncDataSource = Observable<any[]> | Promise<any[]> | (() => Observable<any[]>) | (() => Promise<any[]>);
454
```