ngx-country-selector

A modern, feature-rich Angular country selector component built with Angular Material. This library provides a beautiful, accessible, and highly customizable dropdown for selecting countries with support for flags, country codes, local names, and more.

✨ Features

• 🎨 Built with Angular Material - Leverages Material Design components for consistent UI/UX
• 🏳️ Country Flags - Visual flag representations for all countries
• 🌍 Comprehensive Country Data - Includes country codes, local names, capitals, currencies, and languages
• 🔍 Search & Filter - Built-in search functionality with autocomplete
• ⚡ Performance Optimized - Supports zoneless change detection for better performance
• 🎯 Highly Customizable - Extensive configuration options for appearance and behavior
• ♿ Accessible - Full accessibility support with ARIA attributes
• 📱 Responsive - Works seamlessly across all device sizes
• 🔧 Angular 20 Ready - Compatible with the latest Angular version

🛠️ Built With

• Angular 20+ - Modern Angular framework
• Angular Material 20+ - Material Design components (mat-form-field, mat-autocomplete, mat-input, mat-icon, mat-progress-bar, mat-divider)
• TypeScript - Type-safe development experience
• SCSS - Styled with modern CSS preprocessor

Note: Angular CDK is included as a peer dependency of Angular Material but is not directly used by this library.

This library was generated with Angular CLI version 20.3.2.

📋 Prerequisites

This library requires Angular Material to be installed in your project, as it uses Material Design components like mat-form-field, mat-autocomplete, and mat-input.

If you don't have Angular Material installed:

ng add @angular/material

🚀 Getting started

1. Once your Angular application setup is ready, install the ngx-country-selector library using the following command:

npm i ngx-country-selector

2. Add the CSS Either import the CSS directly to styles.scss file

   @import  "node_modules/ngx-country-selector/assets/styles.css";

   Or, add CSS file in angular.json in the styles array in the build section

    "styles": [
              "node_modules/ngx-country-selector/assets/styles.css",
              "src/styles.scss"
            ],

3. Import CountrySelectorLibraryComponent import CountrySelectorLibraryComponent in module where you want to add the countries dropdown, it may be app-module, some lazy loaded module or a standalone component

     imports: [
    CountrySelectorLibraryComponent
    ],

4. Add the country component to the component where is being used

<lib-country-selector></lib-country-selector>

Properties and their usage

####The below table explains what all Input properties country dropdown accepts and their usage

Events

Reactive forms

 loginForm = new FormGroup({
      username: new FormControl('', [Validators.required]),
      password: new FormControl('', Validators.required),
      country: new FormControl({value: {code:'in'} as ICountry | null, disabled: false},
         Validators.required), // need to send both validator and required input value to make it work
    });

  <lib-country-selector
  [allowedCountryCodes]="allowedCountryCode()"
  [countryListConfig]="config"
  [selectedCountryConfig]="selectedConfig"
  [loading]="loading()"
  [readonly]="readonly() || loading()"
  label="Country"
  [clearable]="!shouldCountryLocked()"
  [customNaming]="{ gb: 'United Kingdom'}"
  formControlName="country"
  (onCountryChange)="onCountryChange($event)"
  error="Country is required"
  [required]="true"
  ></lib-country-selector>

IConfig properties and usage

Config properties can be used to control what will be displayed in the country list and for the selected country.

Exported interface

export interface IConfig {
  hideFlag?: boolean;
  hideCode?: boolean;
  hideName?: boolean;
  showLocalName?: boolean;
  hideSearch?: boolean;
  hideDialCode?: boolean;
  displayCapital?: boolean;
  displayLanguageCode?: boolean;
  displayLanguageName?: boolean;
  displayCurrencyCode?: boolean
  displayCurrencyName?: boolean
  displayCurrencySymbol?: boolean

}

Output on country selection

On country selection output of ICountry type will be emitted. Handle country change event

<lib-country-selector (onCountryChange)="onCountryChange($event)"></lib-country-selector>

  onCountryChange(country: ICountry){
    console.log(country);
  }

output in console

{
    name: 'Afghanistan',
    localName: '‫افغانستان‬‎',
    code: 'AF',
    capital: 'Kabul',
    region: 'AS',
    currency: {
      code: 'AFN',
      name: 'Afghan afghani',
      symbol: '؋',
    },
    language: {
      code: 'ps',
      name: 'Pashto',
    },
    dialling_code: '+93',
    isoCode: '004',
  },

exported ICountry interface

export interface ICountry {
  name?: string;
  localName?: string;
  code?: string;
  capital?: string;
  region?: string;
  currency?: ICurrency
  language?: ILanguage
  dialling_code?: string;
  isoCode?: string;
  demonym?: string;
}

export interface ICurrency {
  code?: string | null;
  name?: string;
  symbol?: string | null;
}

export interface ILanguage {
    code?: string;
    name?: string;
    iso639_2?: string,
    nativeName?: string
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgment

This project includes code and concepts inspired by the following:

1. angular-material-extensions/select-country by Anthony Nahas, licensed under the MIT License.
2. ngx-countries-dropdown by Kapil Kumar, licensed under the MIT License.