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

Property	Type and default values	Description
preferredCountryCodes	Type: string array(string[]),Default value: []	the list of country codes which needs to be displayed on top section. ex. if user provided ['in', 'us'], India and United States will be displayed on top
blockedCountryCodes	Type: string array(string[]),Default value: []	an array of country codes which are not required in the list. Ex. if some client is not servicing some specific countries can be removed from the country dropdown using this.
allowedCountryCodes	Type: string array(string[]),Default value: []	Only countries which will be displayed in the country list
selectedCountryConfig	Type: IConfig (see table below for IConfig properties), Default value: {}	Provides config for the selected country, and controls what all will be displayed. Ex. if the user do not want to display flag for the selected item, can be controlled with this property(refer to config table for details)
countryListConfig	Type: IConfig (see table below for IConfig properties), Default value: {}	Provides config for the country list, and controls what all will be displayed in the country list. Ex. if the user do not want to see flag or dial code or name in the country list, can be controlled with this property(refer to config table for details)
label	Type: string Default value: 'Select country'	`mat-form-field` label's text
placeholderText	Type: string Default value: 'Select country'	To change the default placeholder label.
loading	Type: boolean Default value: false	Whether the component is loading.
readonly	Type: boolean Default value: false	Whether the component is read only.
clearable	Type: boolean Default value: false	To show clear button.
required	Type: boolean Default value: false	Whether the component is required. Note: `FormControl` validator need to be setup too
error	Type: string Default value: ''	To set the error message for required validation.

Events

onCountryChange

Country type ICountry

returns the selected country

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

}

hideFlag	Boolean, Default value: false	to hide flag from country list or selected country
hideCode	Boolean, Default value: false	to hide country code
hideName	Boolean, Default value: false	to hide country name
showLocalName	Boolean, Default value: false	to show local name of the country
hideSearch	Boolean, Default value: false	to hide search field from country list
hideDialCode	Boolean, Default value: false	to hide dial code
displayCapital	Boolean, Default value: false	to display country capital
displayLanguageCode	Boolean, Default value: false	to display country language code
displayLanguageName	Boolean, Default value: false	to display country language name
displayCurrencyCode	Boolean, Default value: false	to display country currency code
displayCurrencyName	Boolean, Default value: false	to display country currency name
displayCurrencySymbol	Boolean, Default value: false	to display country currency symbol

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.