https://github.com/wlucha/ng-country-select
🌍 A smart, multilingual country search with flags and codes made with Angular
https://github.com/wlucha/ng-country-select
angular angular-country angular-material angular19 country-autocomplete country-select mat-autocomplete ng-country-select
Last synced: 13 days ago
JSON representation
🌍 A smart, multilingual country search with flags and codes made with Angular
- Host: GitHub
- URL: https://github.com/wlucha/ng-country-select
- Owner: wlucha
- License: mit
- Created: 2025-01-31T23:26:32.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-27T22:24:46.000Z (about 1 month ago)
- Last Synced: 2025-03-27T22:29:45.262Z (about 1 month ago)
- Topics: angular, angular-country, angular-material, angular19, country-autocomplete, country-select, mat-autocomplete, ng-country-select
- Language: TypeScript
- Homepage: https://wlucha.github.io/ng-country-select/
- Size: 4.2 MB
- Stars: 11
- Watchers: 1
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE-OF-CONDUCT.md
Awesome Lists containing this project
- awesome-angular - ng-country-select - A smart, multilingual country search with flags and codes. (Table of contents / Third Party Components)
- fucking-awesome-angular - ng-country-select - A smart, multilingual country search with flags and codes. (Table of contents / Third Party Components)
README
# 🌍 Angular Material Country Autocomplete
**A smart, multilingual country search with flags and codes made with Angular**
✨ *Enhance your Angular forms with this elegant, high-performance autocomplete* ✨
[](https://github.com/wlucha/ng-country-select/stargazers)
[](https://angular.io/)
[](https://opensource.org/licenses/MIT)
## 📢 Features
- **🅰️ Fully Compatible with Angular 16-19**
This library is designed to work seamlessly with the latest Angular versions (16, 17, 18, and 19).
It leverages modern Angular features while maintaining backward compatibility.
- **🌍 Multi-language Magic**
Supports English, French, Spanish, Italian, German, Arabic, Chinese, Hindi, Bengali, Portuguese and Russian + easily extendable to any language
- **🎌 Flag Images** 🇺🇸 🇩🇪 🇫🇷 🇪🇸 🇮🇹
OS & Browser independent flag images
- **⚡ Optimized Performance**
RxJS-powered search with debounce & virtual scrolling
- **🔍 Smart Search**
Search countries by: ✓ Localized name ✓ Any translation ✓ Alpha2/3 codes
- **🎨 Material Design Excellence**
Seamless integration with Angular Material components
- **🧩 Standalone Component**
Zero boilerplate integration
## 🚀 Demo
Live Demo: [**https://wlucha.github.io/ng-country-select**](https://wlucha.github.io/ng-country-select)
Stackblitz: [https://stackblitz.com/~/github.com/wlucha/ng-country-select](https://stackblitz.com/~/github.com/wlucha/ng-country-select)
## 🌍 Compatibility
| Angular Version | ✅ Supported |
|----------------|-------------|
|  | ✅ Yes |
|  | ✅ Yes |
|  | ✅ Yes |
|  | ✅ Yes |
## 🛠️ Setup in 60 Seconds
## 1. Install Dependencies
### Quick Installation (`ng add`)
```sh
ng add @wlucha/ng-country-select
```
This command will install the `@wlucha/ng-country-select` library + all required dependencies.
#### (Alternative) Install Dependencies manually & update Angular.json styles
```sh
# Install dependencies
npm install --save @angular/material @angular/cdk @angular/animations flag-icons @wlucha/ng-country-select
# Add the flag icon styles to Angular.json "styles" array
"architect": {
"build": {
"options": {
...,
"styles": [
...,
"flag-icons/css/flag-icons.min.css"
]
}
}
}
}
```
### 2. Import Component
```typescript
import { CountrySelectComponent } from '@wlucha/ng-country-select';
@NgModule({
imports: [
CountrySelectComponent,
// ... other imports
]
})
```
### 3. Add Basic Usage
```html
```
## 🎛️ Parameters Worth Exploring
### 🎚️ Inputs
| Parameter | Type | Default | Description |
|----------------------|---------------------------|--------------------|----------------------------------------------------------------------------|
| `defaultCountry` | `Country \| null` | `null` | Sets an initial preselected country |
| `formControl` | `FormControl | `null` | Sets an initial preselected country (FormControl) |
| `selectedCountry` | `Country \| null` | - | Sets a country programmatically (after init) |
| `lang` | `string` | `'en'` | Language for displaying country names (e.g., `en`, `de`, `fr`, `es`, `it`) |
| `searchAllLanguages` | `boolean` | `false` | If `true`, searching will match in **all** available translations |
| `placeholder` | `string` | `'Search country'` | Placeholder text for the input field |
| `debounceTime` | `number` | `100` | Debounce time in milliseconds for the search input |
| `disabled` | `boolean` | `false` | Disables the component if `true` |
| `appearance` | `'fill' \| 'outline'` | `'fill'` | Appearance style of the form field |
| `required` | `boolean` | `false` | Marks the field as required if `true` |
| `showCodes` | `boolean` | `false` | If `true`, shows alpha2/alpha3 codes in the autocomplete results |
| `color` | `ThemePalette` | `'primary'` | Angular Material color palette to use (`'primary'`, `'accent'`, `'warn'`) |
| `includeCountries` | `string[]` | `[]` | List of country codes to include in the dropdown (e.g., `['US', 'DE', 'FR']`) |
| `excludeCountries` | `string[]` | `[]` | List of country codes to exclude from the dropdown (e.g., `['US', 'DE', 'FR']`) |
| `alpha2Only` | `boolean` | `false` | Show only alpha2 codes in the results |
| `alpha3Only` | `boolean` | `false` | Show only alpha3 codes in the results |
| `showFlag` | `boolean` | `true` | Whether the flag should be displayed |
### 🚨 Outputs
| Event | Output | Description |
|---------------------|---------------------|-------------------------------------|
| `countrySelected` | `Country` | Full country object on selection |
| `inputChanged` | `string` | Live search term updates |
| `closed` | `void` | When dropdown closes |
## 💻 Power User Setup
```html
```
## 🌟 Support the Project
**Love this component? Here's how you can help:**
1. ⭐ **Star the repo** (you're awesome!)
2. 🐛 **Report bugs** [here](https://github.com/wlucha/ng-country-select/issues)
3. 💡 **Suggest features**
4. 📢 **Share with your network**
```bash
# Your star fuels development! ⭐
# Clone and explore:
git clone https://github.com/wlucha/ng-country-select.git
````
---
📄 License: MIT
👨💻 Maintainer: Wilfried Lucha
Made with ❤️ & ☕ by Open Source Contributors
## TODO
- more languages
- custom option template
- semantic release