ishansasika · ishansasika · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/.github/workflows/firebase-hosting-merge.yml b/.github/workflows/firebase-hosting-merge.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm i && cd demo && npm i && npm run build
+      - run: npm i --legacy-peer-deps && cd demo && npm i --legacy-peer-deps && npm run build
       - uses: FirebaseExtended/action-hosting-deploy@v0
         with:
           repoToken: ${{ secrets.GITHUB_TOKEN }}

diff --git a/.github/workflows/firebase-hosting-pull-request.yml b/.github/workflows/firebase-hosting-pull-request.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm i && cd demo && npm i && npm run build
+      - run: npm i --legacy-peer-deps && cd demo && npm i --legacy-peer-deps && npm run build
       - uses: FirebaseExtended/action-hosting-deploy@v0
         with:
           repoToken: ${{ secrets.GITHUB_TOKEN }}

diff --git a/.npmrc b/.npmrc
@@ -0,0 +1 @@
+legacy-peer-deps=true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-01-15
+
+> **📌 Version Guide**: Use v3.x for Angular 21+ projects. For Angular 20 projects, use v2.x (latest: v2.3.0). Both versions have feature parity.
+
+### 🚀 Breaking Changes
+
+#### Angular 21 Upgrade
+- **Angular 21.0.5** - Upgraded all Angular packages to version 21.0.5
+- **TypeScript 5.9** - Updated to TypeScript ~5.9.0
+- **Peer Dependencies** - Now requires Angular ^21.0.0
+
+#### API Changes
+- **`paste` Output renamed to `pasteValues`** - The `paste` event output has been renamed to `pasteValues` to avoid conflicts with the native DOM paste event in Angular 21's stricter AOT compilation
+
+### 🔧 Internal Changes
+- Replaced `CommonModule` import with explicit imports (`KeyValuePipe`, `NgTemplateOutlet`)
+- Removed `FormsModule` from component imports (not used in template)
+- Updated demo app for Angular 21 compatibility
+
+### 📦 Migration Guide
+
+**From v2.x to v3.0.0:**
+
+1. Update Angular to 21.0.5:
+   ```bash
+   ng update @angular/core@21 @angular/cli@21
+   ```
+
+2. Update TypeScript to 5.9:
+   ```bash
+   npm install typescript@~5.9.0
+   ```
+
+3. If you were listening to the `paste` event, rename it to `pasteValues`:
+   ```html
+   <!-- Before -->
+   <ng-perfect-select (paste)="onPaste($event)">
+
+   <!-- After -->
+   <ng-perfect-select (pasteValues)="onPaste($event)">
+   ```
+
 ## [2.3.0] - 2026-01-14
 
 ### ✨ New Features

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,14 +4,14 @@ This file provides guidance for AI assistants when working with the angular-perf
 
 ## Project Overview
 
-**angular-perfect-select** is a feature-rich, accessible select component for Angular 20+ applications. It's a port of svelte-perfect-select with 100% feature parity, maintaining react-select API compatibility while leveraging Angular's latest features (standalone components, signals).
+**angular-perfect-select** is a feature-rich, accessible select component for Angular 21+ applications. It's a port of svelte-perfect-select with 100% feature parity, maintaining react-select API compatibility while leveraging Angular's latest features (standalone components, signals).
 
 ## Architecture
 
 ### Project Structure
 - **Root as Library**: Unlike typical Angular workspaces, the root directory IS the library package
 - **Demo as Subdirectory**: Demo application lives in `demo/` subfolder
-- **Standalone Components**: Uses Angular 20 standalone components (no NgModules)
+- **Standalone Components**: Uses Angular 21 standalone components (no NgModules)
 - **Signals-based**: State management uses Angular signals, not RxJS observables
 
 ### Key Directories
@@ -92,7 +92,7 @@ npm run preview
 
 ### DO
 - ✅ Maintain react-select API compatibility (dual naming: isMulti/multiple, isSearchable/searchable, etc.)
-- ✅ Use Angular 20 features (standalone components, signals, new control flow @if/@for)
+- ✅ Use Angular 21 features (standalone components, signals, new control flow @if/@for)
 - ✅ Keep library zero-dependency (only Angular peer deps)
 - ✅ Export all public types via `src/public-api.ts`
 - ✅ Use signals for state management
@@ -261,6 +261,7 @@ Target: >85% coverage
 - High contrast mode support
 
 ## Version History
+- **v3.0.0** (2026-01-15): Angular 21.0.5 upgrade, TypeScript 5.9, renamed `paste` output to `pasteValues`
 - **v2.3.0** (2026-01-14): Fuzzy search, dark mode, loading skeleton, compact mode, custom tag templates, option checkboxes, bulk actions, option sorting
 - **v2.2.0** (2026-01-09): Search result highlighting, tag overflow management
 - **v2.1.0** (2026-01-09): Drag & drop reordering, option pinning
@@ -276,7 +277,7 @@ Target: >85% coverage
 
 ## Notes for AI Assistants
 - This is a port from Svelte, so reference svelte-perfect-select for feature implementations
-- The library uses Angular 20's latest features (standalone, signals)
+- The library uses Angular 21's latest features (standalone, signals)
 - Never add dependencies without explicit approval
 - Always maintain backwards compatibility with react-select API
 - Prioritize accessibility and keyboard navigation

diff --git a/README.md b/README.md
@@ -5,12 +5,31 @@ A modern, feature-rich, and fully accessible select component for Angular applic
 [![npm version](https://badge.fury.io/js/angular-perfect-select.svg)](https://www.npmjs.com/package/angular-perfect-select)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
+## 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:**
+
+```bash
+# 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 20+** - Built with standalone components and signals
+- **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
@@ -73,26 +92,21 @@ A modern, feature-rich, and fully accessible select component for Angular applic
 
 ## Installation
 
-Install using npm:
+See [Version Compatibility](#version-compatibility) above to choose the right version for your Angular project.
 
 ```bash
+# npm
 npm install angular-perfect-select @angular/cdk
-```
-
-> **⚠️ v2.0.0 Breaking Change**: Angular CDK is now a required peer dependency. Make sure to install `@angular/cdk@^20.0.0` alongside the package.
 
-Install using yarn:
-
-```bash
+# yarn
 yarn add angular-perfect-select @angular/cdk
-```
-
-Install using pnpm:
 
-```bash
+# 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)

diff --git a/demo/.npmrc b/demo/.npmrc
@@ -0,0 +1 @@
+legacy-peer-deps=true