Angular Perfect Select

A modern, feature-rich, and fully accessible select component for Angular applications. Built with react-select API compatibility, enhanced animations, and a focus on user experience.

Version Compatibility

Package Version	Angular Version	TypeScript Version
v3.x	Angular 21+	TypeScript 5.9+
v2.x	Angular 20	TypeScript 5.8+

Choose the right version for your project:

# For Angular 21+ projects
npm install angular-perfect-select@^3.0.0 @angular/cdk@^21.0.0

# For Angular 20 projects
npm install angular-perfect-select@^2.3.0 @angular/cdk@^20.0.0

Note: v3.x and v2.x have feature parity. The only difference is Angular version support. If you're on Angular 20, use v2.x. When you upgrade to Angular 21, switch to v3.x.

Features

Core Features

React-Select Compatible - Full API compatibility with react-select
Modern UI - Beautiful design with smooth, enhanced animations
Angular 21+ - Built with standalone components and signals
Async Loading - Load options asynchronously with caching support
Creatable Options - Allow users to create new options on the fly
Search/Filter - Built-in search functionality with custom filter support
Multi-Select - Support for selecting multiple options with animated tag chips
Keyboard Navigation - Full keyboard support (Arrow keys, Enter, Escape, Tab, Backspace)
Accessibility - ARIA labels and comprehensive screen reader support
Forms Integration - Full support for Angular template-driven and reactive forms

Advanced Features

v2.3.0 Features 🎉 NEW

Fuzzy Search - Advanced search algorithm supporting acronym-style matching (e.g., 'fb' matches 'Facebook')
Dark Mode - Automatic dark mode detection with manual override and dedicated dark theme
Loading Skeleton - Modern shimmer skeleton UI while loading async options
Compact Mode - Ultra-dense layout variant with reduced padding for data-heavy UIs
Custom Tag Templates - Full control over multi-select tag rendering with ng-template
Option Checkbox Mode - Display checkboxes next to options for better visual selection feedback
Bulk Actions - Action buttons for performing operations on all selected options
Option Sorting - Built-in sorting modes (alphabetical, recently used, custom comparator)

v2.2.0 Features

Search Result Highlighting - Automatically highlights matching text in options with customizable colors
Tag Overflow Management - Show "+N more" or collapsible tags when exceeding visible limit

v2.1.0 Features

Drag & Drop Reordering - Reorder selected tags in multi-select mode with intuitive drag handles
Option Pinning - Pin frequently used options to the top with persistence support

v2.0.0 Features

Virtual Scrolling - Handle 10,000+ options without performance degradation using Angular CDK
Custom Option Templates - Full control over option rendering with ng-template support
Validation States - Visual error, warning, success, and info states with custom messages
Advanced Keyboard Shortcuts - Ctrl+A, Ctrl+C/V, Home/End, and type-ahead navigation
Copy/Paste Support - Copy selected values and paste comma-separated lists
Option Tooltips - Display additional information on hover with configurable content
Recent Selections - Show recently selected items at top with optional persistence
Infinite Scroll - Load more options as user scrolls with pagination support

v1.1.0 Features

Max Selection Limit - Limit the number of selections in multi-select mode with visual feedback
Search Debounce - Configurable debounce delay for async loading to reduce API calls
Min Search Length - Require minimum characters before filtering with helpful progress indicator

Core Features

Select All / Deselect All - One-click selection for multi-select mode
Option Grouping - Organize options into categories with sticky headers
Icons in Options - Add visual elements (SVG or images) to options
Badges in Options - Display status, roles, or categories with custom colors
Color Themes - 7 beautiful color themes: blue, purple, green, red, orange, pink, dark
Container Sizing - 5 physical container sizes: xs, sm, md, lg, xl
Font Sizing - 5 font size variants: smaller (11px), small (13px), medium (14px), large (16px), larger (18px)
Custom Styles - Inject custom styles for complete control over appearance
Custom Render Functions - getOptionLabel, getOptionValue, isOptionDisabled
Flexible Options - Support for option descriptions and disabled states
Loading States - Built-in loading indicators for sync and async operations
RTL Support - Right-to-left language support
Menu Positioning - Auto, top, or bottom placement with fixed positioning support
Enhanced Animations - Smooth dropdown animations, staggered options, and tag transitions
Modern UI - Beautiful design with enhanced shadows, backdrop blur effects, and rounded corners

Installation

See Version Compatibility above to choose the right version for your Angular project.

# npm
npm install angular-perfect-select @angular/cdk

# yarn
yarn add angular-perfect-select @angular/cdk

# pnpm
pnpm add angular-perfect-select @angular/cdk

⚠️ Important: Angular CDK (@angular/cdk) is a required peer dependency and must be installed alongside the package.

Quick Start

Standalone Component (Recommended)

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { PerfectSelectComponent, SelectOption } from 'angular-perfect-select';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [FormsModule, PerfectSelectComponent],
  template: \`
    <ng-perfect-select
      [options]="options"
      [(ngModel)]="selectedValue"
      placeholder="Select a country..."
    ></ng-perfect-select>
  \`
})
export class DemoComponent {
  selectedValue: any = null;

  options: SelectOption[] = [
    { id: 'sl', label: 'Sri Lanka', value: 'sl' },
    { id: 'ind', label: 'India', value: 'ind' },
    { id: 'pak', label: 'Pakistan', value: 'pak' }
  ];
}

NgModule Usage

import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { PerfectSelectComponent } from 'angular-perfect-select';

@NgModule({
  imports: [
    FormsModule,
    PerfectSelectComponent
  ],
  // ...
})
export class AppModule { }

Usage Examples

Fuzzy Search (v2.3.0)

Enable intelligent fuzzy search for better option matching:

<angular-perfect-select
  [options]="options"
  [enableFuzzySearch]="true"
  [fuzzySearchThreshold]="0.3"
  [fuzzySearchCaseSensitive]="false"
  [isSearchable]="true"
  placeholder="Try searching 'fb' to find 'Facebook'..."
/>

Dark Mode (v2.3.0)

Automatic dark mode detection with system preference:

<angular-perfect-select
  [options]="options"
  [enableAutoThemeDetection]="true"
  [darkModeTheme]="'dark'"
  [lightModeTheme]="'blue'"
  [colorScheme]="'auto'"
  placeholder="Auto dark mode..."
/>

// Manual dark mode override
<angular-perfect-select
  [options]="options"
  [colorScheme]="'dark'"
  placeholder="Always dark mode..."
/>

Loading Skeleton (v2.3.0)

Show modern skeleton UI while loading:

<angular-perfect-select
  [loadOptions]="loadRemoteData"
  [enableLoadingSkeleton]="true"
  [skeletonItemCount]="5"
  [skeletonItemHeight]="40"
  [skeletonAnimationDelay]="800"
  placeholder="Loading with skeleton..."
/>

Compact Mode (v2.3.0)

Dense layout for dashboards and data grids:

<angular-perfect-select
  [options]="options"
  [compactMode]="true"
  placeholder="Compact select..."
/>

Custom Tag Templates (v2.3.0)

Fully customize how multi-select tags are rendered:

<angular-perfect-select
  [options]="options"
  [isMulti]="true"
  [(ngModel)]="selectedValues"
>
  <ng-template #tagTemplate let-option>
    <div class="custom-tag">
      <img [src]="option.avatar" alt="" class="tag-avatar" />
      <span>{{option.label}}</span>
      <span class="tag-badge">{{option.role}}</span>
    </div>
  </ng-template>
</angular-perfect-select>

Option Checkbox Mode (v2.3.0)

Display checkboxes for better visual feedback:

<angular-perfect-select
  [options]="options"
  [isMulti]="true"
  [showOptionCheckboxes]="true"
  [checkboxPosition]="'left'"
  [checkboxStyle]="'filled'"
  placeholder="Select with checkboxes..."
/>

Bulk Actions (v2.3.0)

Add action buttons for selected options:

// Component
bulkActions: BulkAction[] = [
  {
    id: 'export',
    label: 'Export',
    icon: '/assets/export.svg',
    action: (selectedOptions) => this.exportSelected(selectedOptions)
  },
  {
    id: 'delete',
    label: 'Delete All',
    action: (selectedOptions) => this.deleteSelected(selectedOptions)
  }
];

// Template
<angular-perfect-select
  [options]="options"
  [isMulti]="true"
  [enableBulkActions]="true"
  [bulkActions]="bulkActions"
  [bulkActionsPosition]="'above'"
  [bulkActionsLabel]="'Actions:'"
  (bulkActionSelected)="onBulkAction($event)"
/>

Option Sorting (v2.3.0)

Sort options automatically:

// Alphabetical sorting
<angular-perfect-select
  [options]="options"
  [sortMode]="'alphabetical-asc'"
  placeholder="Sorted A-Z..."
/>

// Recently used sorting
<angular-perfect-select
  [options]="options"
  [sortMode]="'recently-used'"
  [recentlyUsedLimit]="10"
  placeholder="Recently used first..."
/>

// Custom sorting
<angular-perfect-select
  [options]="options"
  [sortMode]="'custom'"
  [customSortComparator]="customSort"
  placeholder="Custom sorted..."
/>

// Component
customSort = (a: SelectOption, b: SelectOption) => {
  return a.priority - b.priority;
};

Search Result Highlighting (v2.2.0)

Highlight matching text in options during search:

<angular-perfect-select
  [options]="options"
  [enableSearchHighlight]="true"
  [searchHighlightColor]="'#ffeb3b'"
  [searchHighlightTextColor]="'#000'"
  [isSearchable]="true"
  placeholder="Search with highlighting..."
/>

Tag Overflow Management (v2.2.0)

Show "+N more" when tags exceed limit:

<angular-perfect-select
  [options]="options"
  [isMulti]="true"
  [maxVisibleTags]="3"
  [showMoreTagsText]="'+{count} more'"
  placeholder="Select multiple..."
/>

// With collapsible tags
<angular-perfect-select
  [options]="options"
  [isMulti]="true"
  [maxVisibleTags]="3"
  [collapsibleTags]="true"
  [showAllTagsText]="'Show all'"
  [showLessTagsText]="'Show less'"
  placeholder="Select multiple (collapsible)..."
/>

Drag & Drop Reordering (v2.1.0)

Reorder selected tags in multi-select mode with drag-and-drop:

<angular-perfect-select
  [options]="options"
  [isMulti]="true"
  [enableDragDrop]="true"
  [dragDropPlaceholder]="'Drop here'"
  [dragDropAnimation]="200"
  (reorder)="handleReorder($event)"
/>

// In your component
handleReorder(event: SelectReorderEvent) {
  console.log('Reordered from', event.previousIndex, 'to', event.currentIndex);
  console.log('New order:', event.values);
}

Option Pinning (v2.1.0)

Pin frequently used options to the top of the dropdown:

<angular-perfect-select
  [options]="options"
  [enablePinning]="true"
  [maxPinnedOptions]="3"
  [persistPinnedOptions]="true"
  [pinnedOptionsLabel]="'Favorites'"
  (pin)="handlePin($event)"
/>

// In your component
handlePin(event: SelectPinEvent) {
  console.log('Option', event.option.label, event.pinned ? 'pinned' : 'unpinned');
}

Max Selection Limit (v1.1.0)

Limit the number of selections in multi-select mode:

<ng-perfect-select
  [options]="options"
  [isMulti]="true"
  [maxSelectedOptions]="3"
  maxSelectedMessage="You can only select up to 3 items"
  [(ngModel)]="selectedValues"
></ng-perfect-select>

Search Debounce (v1.1.0)

Add debouncing to async search to reduce API calls:

<ng-perfect-select
  [options]="[]"
  [loadOptions]="loadCountries"
  [debounceTime]="500"
  [(ngModel)]="selectedCountry"
></ng-perfect-select>

loadCountries = async (searchTerm: string): Promise<SelectOption[]> => {
  const response = await fetch(`/api/countries?search=${searchTerm}`);
  return response.json();
};

Minimum Search Length (v1.1.0)

Require minimum characters before filtering options:

<ng-perfect-select
  [options]="largeDataset"
  [minSearchLength]="3"
  minSearchMessage="Please enter at least 3 characters"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

Virtual Scrolling (v2.0.0)

Handle large datasets (10,000+ options) with virtual scrolling:

<ng-perfect-select
  [options]="hugeDataset"
  [enableVirtualScroll]="true"
  [virtualScrollItemSize]="40"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

Custom Option Templates (v2.0.0)

Provide custom rendering for options:

<ng-perfect-select [options]="options" [(ngModel)]="selectedValue">
  <ng-template #optionTemplate let-option let-selected="selected">
    <div class="custom-option">
      <img [src]="option.avatar" />
      <div>
        <strong>{{option.label}}</strong>
        <span>{{option.email}}</span>
      </div>
      @if (selected) {
        <span class="badge">Selected</span>
      }
    </div>
  </ng-template>
</ng-perfect-select>

Validation States (v2.0.0)

Visual validation feedback for forms:

<ng-perfect-select
  [options]="options"
  validationState="error"
  validationMessage="Please select at least one option"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

<!-- Available states: 'error', 'warning', 'success', 'info', 'default' -->

Advanced Keyboard Shortcuts (v2.0.0)

Power-user keyboard navigation:

Ctrl/Cmd+A: Select all options (multi-select)
Ctrl/Cmd+C: Copy selected values to clipboard
Ctrl/Cmd+V: Paste comma-separated values (multi-select)
Home: Jump to first option
End: Jump to last option
Type-ahead: Type characters to jump to matching option

<ng-perfect-select
  [options]="options"
  [enableAdvancedKeyboard]="true"
  [enableCopyPaste]="true"
  [typeAheadDelay]="500"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

Copy/Paste Support (v2.0.0)

Copy selected values and paste comma-separated lists:

<ng-perfect-select
  [options]="options"
  [isMulti]="true"
  [enableCopyPaste]="true"
  [copyDelimiter]="', '"
  [pasteDelimiter]=","
  (copy)="onCopy($event)"
  (paste)="onPaste($event)"
  [(ngModel)]="selectedValues"
></ng-perfect-select>

Option Tooltips (v2.0.0)

Show additional information on hover:

<ng-perfect-select
  [options]="optionsWithTooltips"
  [showTooltips]="true"
  [tooltipDelay]="300"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

// Options with tooltip property
options = [
  { id: 1, label: 'Option 1', value: 'opt1', tooltip: 'This is a helpful tooltip' },
  { id: 2, label: 'Option 2', value: 'opt2', tooltip: 'Additional information here' }
];

Recent Selections (v2.0.0)

Display recently selected items at the top:

<ng-perfect-select
  [options]="options"
  [showRecentSelections]="true"
  [recentSelectionsLimit]="5"
  [recentSelectionsLabel]="'Recently Selected'"
  [enableRecentSelectionsPersistence]="true"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

Infinite Scroll (v2.0.0)

Load more options as user scrolls:

<ng-perfect-select
  [options]="options"
  [enableInfiniteScroll]="true"
  [infiniteScrollThreshold]="80"
  (scrollEnd)="loadMoreOptions($event)"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

loadMoreOptions(event: SelectScrollEndEvent) {
  // Load more data when user scrolls to 80% of the list
  this.fetchMoreOptions().then(newOptions => {
    this.options = [...this.options, ...newOptions];
  });
}

Multi-Select with Tags

<ng-perfect-select
  [options]="options"
  [isMulti]="true"
  placeholder="Select multiple..."
  [(ngModel)]="selectedValues"
></ng-perfect-select>

Async Loading with Caching

<ng-perfect-select
  [loadOptions]="loadRemoteData"
  [cacheOptions]="true"
  [defaultOptions]="true"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

Creatable Options

<ng-perfect-select
  [options]="options"
  [isCreatable]="true"
  (createOption)="onCreateOption($event)"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

With Themes and Styling

<ng-perfect-select
  [options]="options"
  theme="purple"
  selectSize="large"
  containerSize="lg"
  [(ngModel)]="selectedValue"
></ng-perfect-select>

Documentation

For complete documentation, examples, and interactive playground, visit: https://angular-perfect-select.ishansasika.dev

Name		Name	Last commit message	Last commit date
Latest commit History 93 Commits
.github/workflows		.github/workflows
demo		demo
src		src
.firebaserc		.firebaserc
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
angular.json		angular.json
firebase.json		firebase.json
ng-package.json		ng-package.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.lib.json		tsconfig.lib.json
tsconfig.lib.prod.json		tsconfig.lib.prod.json
tsconfig.spec.json		tsconfig.spec.json

License

ishansasika/angular-perfect-select

Folders and files

Latest commit

History

Repository files navigation

Angular Perfect Select

Version Compatibility

Features

Core Features

Advanced Features

v2.3.0 Features 🎉 NEW

v2.2.0 Features

v2.1.0 Features

v2.0.0 Features

v1.1.0 Features

Core Features

Installation

Quick Start

Standalone Component (Recommended)

NgModule Usage

Usage Examples

Fuzzy Search (v2.3.0)

Dark Mode (v2.3.0)

Loading Skeleton (v2.3.0)

Compact Mode (v2.3.0)

Custom Tag Templates (v2.3.0)

Option Checkbox Mode (v2.3.0)

Bulk Actions (v2.3.0)

Option Sorting (v2.3.0)

Search Result Highlighting (v2.2.0)

Tag Overflow Management (v2.2.0)

Drag & Drop Reordering (v2.1.0)

Option Pinning (v2.1.0)

Max Selection Limit (v1.1.0)

Search Debounce (v1.1.0)

Minimum Search Length (v1.1.0)

Virtual Scrolling (v2.0.0)

Custom Option Templates (v2.0.0)

Validation States (v2.0.0)

Advanced Keyboard Shortcuts (v2.0.0)

Copy/Paste Support (v2.0.0)

Option Tooltips (v2.0.0)

Recent Selections (v2.0.0)

Infinite Scroll (v2.0.0)

Multi-Select with Tags

Async Loading with Caching

Creatable Options

With Themes and Styling

Documentation

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Languages

Packages