ngx-country-selector

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

• ✨ Signal Forms Support - Native support for Angular's new Signal Forms API (FormValueControl)
• 🎨 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 22 Ready - Compatible with the latest Angular version

• Angular 22+ - Modern Angular framework with Signal Forms
• Angular Material 22+ - Material Design components (mat-form-field, mat-autocomplete, mat-input, mat-icon, mat-progress-bar, mat-divider)
• TypeScript 6.0 - Type-safe development experience
• SCSS - Styled with modern CSS preprocessor
• Signal Forms API - Implements FormValueControl interface for modern form integration

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 and updated to Angular 22.

The major version of the library matches the Angular major version it is built for.

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

@angular/material and @angular/forms are peer dependencies of this library (along with @angular/core and @angular/common).

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>

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

Recommended for new applications:

import { form, FormField, required } from '@angular/forms/signals';
import { signal } from '@angular/core';

// Define your model
type LoginModel = {
  username: string;
  password: string;
  country: ICountry | null;
};

// Create signal-based form
vm = signal<LoginModel>({
  username: '',
  password: '',
  country: null
});

loginForm = form(this.vm, (p) => {
  required(p.username, { message: 'Username is required' });
  required(p.password, { message: 'Password is required' });
  required(p.country, { message: 'Country is required' });
});

<!-- Import the FormField directive in your component -->
<lib-country-selector
  [formField]="loginForm.country"
  [allowedCountryCodes]="allowedCountryCode()"
  [countryListConfig]="config"
  [selectedCountryConfig]="selectedConfig"
  [loading]="loading()"
  label="Country"
  [clearable]="true"
  [customNaming]="{ gb: 'United Kingdom' }"
  (onCountryChange)="onCountryChange($event)"
  error="Country is required"
></lib-country-selector>

Key Benefits:

• ✨ Reactive updates with signals
• 🚀 Better performance with fine-grained reactivity
• 🎯 Type-safe form models
• 🔧 Automatic validation and error handling

Upgrading from 21.x: Signal Forms became stable in Angular 22 and the directive was renamed. Replace the Field import with FormField and [field]="..." with [formField]="...".

For applications using traditional reactive forms:

loginForm = new FormGroup({
  username: new FormControl('', [Validators.required]),
  password: new FormControl('', Validators.required),
  // a value that only carries the code is enough, the component looks the country up
  country: new FormControl({value: {code:'in'} as ICountry | null, disabled: false},
    Validators.required), // the validator also drives the required marker and the error
});

<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"
></lib-country-selector>

Note: The component supports both Signal Forms and traditional Reactive Forms (formControl / formControlName), allowing for gradual migration. Disabled, touched, required and error state are picked up from the FormControl automatically, so no extra inputs are needed.

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

}

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',
  },

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
}

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

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.