@wlucha/ng-country-select
Version:
A smart, multilingual country search with flags and codes
248 lines (197 loc) โข 11.9 kB
Markdown
# ๐ 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)
<p align="center">
<img src="https://github.com/user-attachments/assets/e7946ea0-14ea-414c-8f48-c11dd257bfd1">
</p>
## ๐ข Features
- **๐
ฐ๏ธ Fully Compatible with Angular 16-21**
This library is designed to work seamlessly with the latest Angular versions (16, 17, 18, 19, 20, 21).
It leverages modern Angular features while maintaining backward compatibility.
- **๐ Multi-language Magic**
Supports English, French, Spanish, Italian, German, Arabic, Chinese, Hindi, Bengali, Portuguese, Russian โ plus easily extendable to **any custom language** via `provideCountrySelectConfig()`
- **๐ 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 |
|  | โ
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
<ng-country-select
[lang]="'en'"
(countrySelected)="handleSelection($event)"
></ng-country-select>
```
## ๐๏ธ Parameters Worth Exploring
### ๐๏ธ Inputs
| Parameter | Type | Default | Description |
|---------------------------------------|------------------------------|-----------------------|------------------------------------------------------------------------------------------|
| `defaultCountry` | `Country \| null` | `null` | Sets an initial preselected country |
| `formControl` | `FormControl<Country \| null>` | `new FormControl(null)` | Reactive form control for the country select |
| `selectedCountry` | `Country \| null` | - | Sets a country programmatically (after init) |
| `selectedCountryByAlpha2` | `string` | - | Set a country programmatically by its alpha2 code |
| `selectedCountryByAlpha3` | `string` | - | Set a country programmatically by its alpha3 code |
| `selectedCountryByCurrentTranslation` | `string` | - | Set a country programmatically by its name in the current language |
| `lang` | `string` | `'en'` | Language for displaying country names โ supports built-in and custom languages |
| `searchAllLanguages` | `boolean` | `false` | If `true`, searching will match in **all** available translations |
| `placeholder` | `string` | `'Search country'` | Placeholder text for the input field |
| `label` | `string \| undefined` | `undefined` | Custom label for the form field |
| `showLabel` | `boolean` | `true` | Whether to show the label (uses `label` or `placeholder` as fallback) |
| `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` |
| `requiredErrorMessage` | `string` | `'A country is required'` | Error message shown when the field is required and empty |
| `showRequiredErrorMessage` | `boolean` | `false` | Whether to show the built-in required error message |
| `showCodes` | `boolean` | `false` | If `true`, shows alpha2/alpha3 codes in the autocomplete results |
| `color` | `ThemePalette` | `'primary'` | Angular Material color palette (`'primary'`, `'accent'`, `'warn'`) |
| `includeCountries` | `string[]` | `[]` | List of alpha2 country codes to include (e.g., `['us', 'de', 'fr']`) |
| `excludeCountries` | `string[]` | `[]` | List of alpha2 country codes to exclude (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 | Type | Description |
|---------------------|-------------------|--------------------------------------------|
| `countrySelected` | `Country` | Emits the full country object on selection |
| `inputChanged` | `string` | Emits the current search term on change |
| `closed` | `void` | Emits when the autocomplete panel closes |
## ๐ป Power User Setup
```html
<ng-country-select
[lang]="'en'"
[formControl]="countryControl"
[searchAllLanguages]="true"
[showCodes]="true"
[debounceTime]="200"
[required]="true"
[requiredErrorMessage]="'A country is required'"
[showRequiredErrorMessage]="true"
[disabled]="false"
[appearance]="'outline'"
[placeholder]="'Search country'"
[color]="primary"
[alpha2Only]="false"
[alpha3Only]="false"
[showFlag]="true"
[excludeCountries]="['US', 'DE', 'FR']"
(countrySelected)="onCountrySelect($event)"
(inputChanged)="trackSearchTerm($event)"
></ng-country-select>
```
## ๐ Custom Language Support
You can add custom translations or override existing ones using `provideCountrySelectConfig()`.
### Adding extra translations (e.g. Polish)
```typescript
// app.config.ts
import { provideCountrySelectConfig } from '@wlucha/ng-country-select';
export const appConfig: ApplicationConfig = {
providers: [
provideCountrySelectConfig({
extraTranslations: {
de: { pl: 'Niemcy', ja: 'ใใคใ' },
at: { pl: 'Austria', ja: 'ใชใผในใใชใข' },
fr: { pl: 'Francja', ja: 'ใใฉใณใน' },
// ... add translations for all countries
}
})
]
};
```
Then use the custom language in your template:
```html
<ng-country-select
[lang]="'pl'"
[placeholder]="'Szukaj kraju'"
></ng-country-select>
```
### Replacing the entire country list
For full control, you can replace the built-in country list entirely:
```typescript
provideCountrySelectConfig({
countries: [
{
alpha2: 'de',
alpha3: 'deu',
translations: { en: 'Germany', pl: 'Niemcy', ja: 'ใใคใ' }
},
// ... your custom list
]
})
```
### Exported symbols
| Symbol | Type | Description |
|-------------------------------|-------------------|------------------------------------------|
| `provideCountrySelectConfig` | `function` | Provider helper for app config |
| `COUNTRY_SELECT_CONFIG` | `InjectionToken` | Token for advanced DI scenarios |
| `CountrySelectConfig` | `interface` | Configuration type |
## ๐ 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