or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-services.mdindex.mdng-option-highlight.mdng-select-component.mdtemplate-directives.mdtypes-interfaces.md
tile.json

tessl/npm-ng-select--ng-select

Angular ng-select - All in One UI Select, Multiselect and Autocomplete library providing comprehensive select component functionality

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ng-select/ng-select@20.1.x

To install, run

npx @tessl/cli install tessl/npm-ng-select--ng-select@20.1.0

index.mddocs/

Angular ng-select

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.

Package Information

  • Package Name: @ng-select/ng-select
  • Package Type: npm (Angular library)
  • Language: TypeScript/Angular
  • Installation: npm install @ng-select/ng-select

Core Imports

For standalone components:

import { NgSelectComponent, NgOptionComponent } from '@ng-select/ng-select';

For module-based applications:

import { NgSelectModule } from '@ng-select/ng-select';

Template directives (standalone):

import { 
  NgItemLabelDirective, 
  NgOptionTemplateDirective, 
  NgLabelTemplateDirective 
} from '@ng-select/ng-select';

Configuration:

import { NgSelectConfig } from '@ng-select/ng-select';

Basic Usage

import { Component } from '@angular/core';
import { NgSelectComponent, NgOptionComponent } from '@ng-select/ng-select';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [NgSelectComponent, NgOptionComponent],
  template: `
    <ng-select 
      [(ngModel)]="selectedCity"
      placeholder="Select a city"
      [clearable]="true"
      [searchable]="true">
      <ng-option *ngFor="let city of cities" [value]="city.id">
        {{ city.name }}
      </ng-option>
    </ng-select>
  `
})
export class ExampleComponent {
  cities = [
    {id: 1, name: 'New York'},
    {id: 2, name: 'London'},
    {id: 3, name: 'Tokyo'}
  ];
  selectedCity: number | null = null;
}

For multi-select:

@Component({
  template: `
    <ng-select 
      [(ngModel)]="selectedCities"
      [multiple]="true"
      placeholder="Select cities">
      <ng-option *ngFor="let city of cities" [value]="city.id">
        {{ city.name }}
      </ng-option>
    </ng-select>
  `
})
export class MultiSelectComponent {
  selectedCities: number[] = [];
  cities = [/* ... */];
}

Architecture

Angular ng-select is built around several key components:

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

Capabilities

Core Select Component

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

@Component({
  selector: 'ng-select',
  // ... component implementation
})
export class NgSelectComponent implements ControlValueAccessor {
  // Core selection properties
  @Input() items: any[];
  @Input() bindLabel: string;
  @Input() bindValue: string;
  @Input() multiple: boolean;
  @Input() placeholder: string;
  @Input() disabled: boolean;
  @Input() readonly: boolean;
  
  // Display and interaction properties
  @Input() clearable: boolean;
  @Input() searchable: boolean;
  @Input() loading: boolean;
  @Input() virtualScroll: boolean;
  @Input() closeOnSelect: boolean;
  @Input() hideSelected: boolean;
  
  // Customization properties
  @Input() appearance: string;
  @Input() dropdownPosition: DropdownPosition;
  @Input() appendTo: string;
  @Input() maxSelectedItems: number;
  
  // Events
  @Output() change: EventEmitter<any>;
  @Output() open: EventEmitter<void>;
  @Output() close: EventEmitter<void>;
  @Output() focus: EventEmitter<void>;
  @Output() blur: EventEmitter<void>;
  @Output() search: EventEmitter<{term: string, items: any[]}>;
  @Output() clear: EventEmitter<void>;
  @Output() add: EventEmitter<any>;
  @Output() remove: EventEmitter<any>;
  @Output() scroll: EventEmitter<{start: number, end: number}>;
  @Output() scrollToEnd: EventEmitter<void>;
}

Core Select Component

Template Customization

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

// Item display templates
@Directive({ selector: '[ng-option-tmp]' })
export class NgOptionTemplateDirective {}

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

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

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

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

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

@Directive({ selector: '[ng-loadingtext-tmp]' })
export class NgLoadingTextTemplateDirective {}

Template Customization

Configuration and Services

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

@Injectable()
export class NgSelectConfig {
  placeholder: string;
  notFoundText: string;
  typeToSearchText: string;
  addTagText: string;
  loadingText: string;
  clearAllText: string;
  disableVirtualScroll: boolean;
  openOnEnter: boolean;
  appendTo: string;
  bindValue: string;
  bindLabel: string;
  // ... additional configuration properties
}

@Injectable()
export class NgDropdownPanelService {
  dimensions: PanelDimensions;
  calculateItems(scrollPos: number, itemsLength: number, buffer: number): ItemsRangeResult;
}

Configuration and Services

Option Highlighting

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

@Directive({
  selector: '[ngOptionHighlight]'
})
export class NgOptionHighlightDirective {
  @Input('ngOptionHighlight') term: string;
}

Option Highlighting

Types and Interfaces

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

interface NgOption {
  [name: string]: any;
  index?: number;
  htmlId?: string;
  selected?: boolean;
  disabled?: boolean;
  marked?: boolean;
  label?: string;
  value?: string | any;
  parent?: NgOption;
  children?: NgOption[];
}

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

enum KeyCode {
  Tab = 'Tab',
  Enter = 'Enter',
  Esc = 'Escape',
  Space = ' ',
  ArrowUp = 'ArrowUp',
  ArrowDown = 'ArrowDown',
  Backspace = 'Backspace'
}

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

Types and Interfaces