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.

✨ Features

• ✨ 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 21 Ready - Compatible with the latest Angular version

🛠️ Built With

• Angular 21+ - Modern Angular framework with Signal Forms
• Angular Material 21+ - Material Design components (mat-form-field, mat-autocomplete, mat-input, mat-icon, mat-progress-bar, mat-divider)
• TypeScript 5.9+ - 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 21.

📋 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

Signal Forms (Angular 21+)

Recommended for Angular 21+ applications:

import { form, Field, 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 Field directive in your component -->
<lib-country-selector
  [field]="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

Reactive Forms (Traditional)

For applications using traditional 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>

Note: The component supports both Signal Forms and traditional Reactive Forms, allowing for gradual migration.

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.