npm package: @jezmaghuyop/select-country
Description: Fork of @angular-material-extensions/select-country updated for Angular 19 support. Original: https://github.com/angular-material-extensions/select-country
Author: Jez Reel Maghuyop
Latest version: 19.0.5

# @jezmaghuyop/select-country

> **Fork of** [angular-material-extensions/select-country](https://github.com/angular-material-extensions/select-country)  
> Updated for **Angular 19**, standalone components, Ivy partial compilation, and optional language overrides.

<p align="center">
  <img alt="angular-material-extensions's logo"
   height="256px" width="256px" style="text-align: center;"
   src="https://cdn.jsdelivr.net/gh/angular-material-extensions/select-country@master/assets/angular-material-extensions-logo.svg">
</p>

# @jezmaghuyop/select-country - Angular Material component that allow users to select a country or nationality with an autocomplete feature

[![npm version](https://badge.fury.io/js/%40angular-material-extensions%2Fselect-country.svg)](https://badge.fury.io/js/%40angular-material-extensions%2Fselect-country)
[![npm demo](https://img.shields.io/badge/demo-online-ed1c46.svg)](https://angular-material-extensions.github.io/select-country)
[![docs: typedoc](https://img.shields.io/badge/docs-typedoc-4D0080.svg)](https://angular-material-extensions.github.io/select-country/doc/index.html)
[![Join the chat at https://gitter.im/angular-material-extensions/Lobby](https://badges.gitter.im/angular-material-extensions/Lobby.svg)](https://gitter.im/angular-material-extensions/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/angular-material-extensions/select-country.svg?branch=master)](https://travis-ci.org/angular-material-extensions/select-country)
[![codecov](https://codecov.io/gh/angular-material-extensions/select-country/branch/master/graph/badge.svg)](https://codecov.io/gh/angular-material-extensions/select-country)
[![Greenkeeper Badge](https://badges.greenkeeper.io/angular-material-extensions/select-country.svg)](https://greenkeeper.io/)
[![license](https://img.shields.io/github/license/angular-material-extensions/select-country.svg?style=flat-square)](https://github.com/angular-material-extensions/select-country/blob/master/LICENSE)

<p align="center">
  <img alt="@jezmaghuyop/select-country demonstration" style="text-align: center;"
   src="https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/v0.2.0/select-country.gif">
</p>

<p align="center">
  <img alt="@jezmaghuyop/select-country demonstration" style="text-align: center;"
   src="https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/v0.2.0/select-country.png">
</p>

## Built by and for developers :heart:

Do you have any question or suggestion ? Please do not hesitate to contact us!
Alternatively, provide a PR | open an appropriate issue [here](https://github.com/angular-material-extensions/select-country/issues)

If you like this project, support [angular-material-extensions](https://github.com/angular-material-extensions)
by starring :star: and sharing it :loudspeaker:

## Table of Contents

- [Demo](#demo)
- [Components](#components)
- [Dependencies](#dependencies)
- [Installation](#installation)
- [API](#api)
- [Usage](#usage)
- [Run Demo App Locally](#run-demo-app-locally)
- [Other Angular Libraries](#other-angular-libraries)
- [Support](#support)
- [License](#license)

<a name="demo"/>

## [Demo](https://angular-material-extensions.github.io/select-country)

View all the directives and components in action at [https://angular-material-extensions.github.io/select-country](https://angular-material-extensions.github.io/select-country)

<a name="components"/>

## Library's components

- `<mat-select-country>` used to display the main component

---

<a name="dependencies"/>

## Dependencies

- [Angular](https://angular.io) developed and tested with `17.x`

---

<a name="installation"/>

## [Installation](https://angular-material-extensions.github.io/select-country/getting-started)

## 1. Install via _ng add_. (Recommended)

If Angular Material Design is not setup, just run `ng add @angular/material` [learn more](https://material.angular.io/guide/getting-started)

Now add the library via the `angular schematics`

```shell
ng add @jezmaghuyop/select-country
```

## 2. Install via _npm_. (Alternative)

Install peer dependencies

```shell
npm i svg-country-flags -s
```

then update your `angular.json` like below (svg-country-flags)

```json
"assets": [
    "src/favicon.ico",
    "src/assets",
    {
        "glob": "**/*",
        "input": "./node_modules/svg-country-flags/svg",
        "output": "src/assets/svg-country-flags/svg"
    }
]
```

Now install `@jezmaghuyop/select-country` via:

```shell
npm install --save @jezmaghuyop/select-country
```

### Import the library

If you installed the library via angular schematics, you can skip this step

Once installed you need to import the main module and the `HttpClientModule`:

```js
import { MatSelectCountryModule } from "@jezmaghuyop/select-country";
```

```typescript
import { MatSelectCountryModule } from '@jezmaghuyop/select-country';
import {HttpClientModule} from '@angular/common/http';

@NgModule({
    declarations: [AppComponent, ...],
    imports: [
        // you can use 'br' | 'de' | 'en' | 'es' | 'fr' | 'hr' | 'hu' | 'it' | 'nl' | 'pt' --> MatSelectCountrySupportedLanguages
        // you can leave it empty `MatSelectCountryModule.forRoot()` which defaults to 'en'
        MatSelectCountryModule.forRoot('de'), 
        HttpClientModule,
        ...
    ],
    bootstrap: [AppComponent]
})
export class AppModule {
}
```

in other modules

```typescript
import { MatSelectCountryModule } from '@jezmaghuyop/select-country';
import {HttpClientModule} from '@angular/common/http';

@NgModule({
    declarations: [AppComponent, ...],
    imports: [
        MatSelectCountryModule, 
        HttpClientModule, 
        ...
    ],
    bootstrap: [AppComponent]
})
export class AppModule {
}
```

Other modules in your application like for lazy loading import `MatSelectCountryModule` into your feature module:

<a name="api"/>

## API

### `<mat-select-country>` used to display the main component - [see the demo examples](https://angular-material-extensions.github.io/select-country/examples)

| option            |    bind    |           type           |             default             | description                                                                                        |
| :---------------- | :--------: | :----------------------: | :-----------------------------: | :------------------------------------------------------------------------------------------------- |
| value             | `Input()`  |        `Country`         |                -                | the selected country (pass an empty Country object with alpha2 code populated to do alpha2 lookup) |
| appearance        | `Input()`  | `MatFormFieldAppearance` |                -                | Possible appearance styles for `mat-form-field` ('legacy', 'standard', 'fill' or 'outline')        |
| countries         | `Input()`  |       `Country[]`        | All countries stored in the lib | Countries that should be loaded - predefine the countries that you only need!                      |
| label             | `Input()`  |        `boolean`         |                -                | `mat-form-field` label's text                                                                      |
| itemsLoadSize     | `Input()`  |         `number`         |                -                | the number of countries that should be fetched --> improves the performance                        |
| placeHolder       | `Input()`  |        `boolean`         |                -                | input placeholder text                                                                             |
| disabled          | `Input()`  |        `boolean`         |                -                | Whether the component is disabled                                                                  |
| loading           | `Input()`  |        `boolean`         |                -                | Whether the component is loading                                                                   |
| nullable          | `Input()`  |        `boolean`         |                -                | Whether the component is able to emit `null`                                                       |
| readonly          | `Input()`  |        `boolean`         |                -                | Whether the component is read only                                                                 |
| tabIndex          | `Input()`  |    `number \| string`    |                -                | Whether the component can be focused, and where it participates in sequential keyboard navigation  |
| showCallingCode   | `Input()`  |        `boolean`         |              false              | Whether the component to show the country's calling code in the label and selection                |
| class             | `Input()`  |         `string`         |                -                | Class attribute apply style to input text or validation ignore (optional)                          |
| language          | `Input()`  |         `string`         |                -                | the language, if not specified MatSelectCountryModule.forRoot('XX') will be used (optional)        |
| name              | `Input()`  |         `string`         |            'country'            | the attribute name of the input element                                                            |
| autocomplete      | `Input()`  |         `string`         |                -                | the attribute autocomplete of the input element, to avoid suggestion of some browsers put 'no'     |
| onCountrySelected | `Output()` | `EventEmitter<Country>`  |                -                | emits the selected country as object (see the interface below)                                     |

```typescript
interface Country {
  name: string;
  alpha2Code: string;
  alpha3Code: string;
  numericCode: string;
  callingCode: string;
}
```

<a name="usage"/>

## [Usage](https://angular-material-extensions.github.io/select-country)

add the `<mat-select-country>` element to your template:

```html
<mat-select-country>
</mat-select-country>
```

<p align="center">
  <img alt="@jezmaghuyop/select-country demonstration" style="text-align: center;"
   src="https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/v0.2.0/example_full.png">
</p>

<p align="center">
  <img alt="@jezmaghuyop/select-country demonstration" style="text-align: center;"
   src="https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/v0.2.0/example3.png">
</p>

<p align="center">
  <img alt="@jezmaghuyop/select-country demonstration" style="text-align: center;"
   src="https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/v0.2.0/example2.png">
</p>

#### Use the library with reactive forms

### option 1 with Reactive Forms

```html
<mat-select-country appearance="outline"
                    label="Country"
                    [formControl]="countryFormControl"
                    (onCountrySelected)="onCountrySelected($event)">
</mat-select-country>
```

### option 2 with Reactive Forms

```html
<form [formGroup]="countryFormGroup">
    <div fxLayoutAlign="center">
      <mat-select-country appearance="outline"
                          label="Country"
                          class="className"
                          formControlName="country"
                          (onCountrySelected)="onCountrySelected($event)">
      </mat-select-country>
    </div>
  </form>
```

```typescript
import { Component, OnInit } from "@angular/core";
import { FormControl } from "@angular/forms";

import { Country } from "@jezmaghuyop/select-country";

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.scss"],
})
export class AppComponent implements OnInit {
  title = "select-country";

  countryFormControl = new FormControl();
  countryFormGroup: FormGroup;

  constructor(private formBuilder: FormBuilder) {
    angulartics2GoogleAnalytics.startTracking();
  }

  ngOnInit(): void {
    this.countryFormGroup = this.formBuilder.group({
      country: [],
    });

    this.countryFormGroup
      .get("country")
      .valueChanges.subscribe((country) =>
        console.log(
          'this.countryFormGroup.get("country").valueChanges',
          country
        )
      );

    this.countryFormControl.valueChanges.subscribe((country) =>
      console.log("this.countryFormControl.valueChanges", country)
    );
  }

  onCountrySelected($event: Country) {
    console.log($event);
  }
}
```

### Predefine your countries to load

```html
<mat-select-country appearance="outline"
                    label="Country"
                    [countries]="predefinedCountries"
                    (onCountrySelected)="onCountrySelected($event)">
</mat-select-country>
```

```typescript
import {Country} from '@jezmaghuyop/select-country';

predefinedCountries: Country[] = [
  {
    name: 'Germany',
    alpha2Code: 'DE',
    alpha3Code: 'DEU',
    numericCode: '276',
    callingCode: '+49'
  },
  {
    name: 'Greece',
    alpha2Code: 'GR',
    alpha3Code: 'GRC',
    numericCode: '300',
    callingCode: '+30'
  },
  {
    name: 'France',
    alpha2Code: 'FR',
    alpha3Code: 'FRA',
    numericCode: '250',
    callingCode: '+33'
  },
  {
    name: 'Belgium',
    alpha2Code: 'BE',
    alpha3Code: 'BEL',
    numericCode: '056',
    callingCode: '+32'
  }
];
```

Result:

<p align="center">
  <img alt="@jezmaghuyop/select-country demonstration" style="text-align: center;"
   src="https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/v2.1.0/predefined.png">
</p>

### Improve performance - use the `itemsLoadSize` property

```html
<mat-select-country appearance="outline"
                    label="Country"
                    [itemsLoadSize]="5">
</mat-select-country>
```

only 5 countries will fetched!

### Change language dynamically - use the `language` property

```html
<mat-select-country appearance="outline"
                    label="Country"
                    [language]="languageSelected"
                    (onCountrySelected)="onCountrySelected($event)">
</mat-select-country>
```

<a name="run-demo-app-locally"/>

### Run Demo App Locally

Build the library

```bash
$ npm run build:lib
```

Serve the demo app

```bash
$ npm start
```

## Other Angular Libraries

- [ngx-auth-firebaseui](https://github.com/AnthonyNahas/ngx-auth-firebaseui)
- [ngx-linkifyjs](https://github.com/AnthonyNahas/ngx-linkifyjs)
- [@angular-material-extensions/password-strength](https://github.com/angular-material-extensions/password-strength)
- [@angular-material-extensions/google-maps-autocomplete](https://github.com/angular-material-extensions/google-maps-autocomplete)
- [@angular-material-extensions/link-preview](https://github.com/angular-material-extensions/link-preview)
- [@angular-material-extensions/fab-menu](https://github.com/angular-material-extensions/fab-menu)
- [@angular-material-extensions/pages](https://github.com/angular-material-extensions/pages)
- [@angular-material-extensions/contacts](https://github.com/angular-material-extensions/contacts)

---

<a name="who_is_using_this_lib"/>

## Who is using this library?

[nahaus.de](https:/nahaus.de) - Digital and Automated Real Estate Management

To put your project here, please drop an appropriate PR

---

<a name="support"/>

## Support

- Drop an email to: [Anthony Nahas](mailto:anthony.na@hotmail.de)
- or open an appropriate [issue](https://github.com/angular-material-extensions/select-country/issues)
- let us chat on [Gitter](https://gitter.im/angular-material-extensions/Lobby)

Built by and for developers :heart: we will help you :punch:

---

![jetbrains logo](https://raw.githubusercontent.com/angular-material-extensions/select-country/HEAD/assets/jetbrains-variant-4_logos/jetbrains-variant-4.png)

This project is supported by [jetbrains](https://www.jetbrains.com/) with 1 ALL PRODUCTS PACK OS LICENSE incl. [webstorm](https://www.jetbrains.com/webstorm)

---

<a name="license"/>

## License

Copyright (c) 2020-2024 [Anthony Nahas](https://github.com/AnthonyNahas) (forked by [Jez Reel Maghuyop](https://github.com/jezmaghuyop/select-country)).

Original project: https://github.com/angular-material-extensions/select-country

Licensed under the MIT License (MIT) <p align="center">
<img alt="angular-material-extensions's logo"
                                                                                                             height="92px" width="92px" style="text-align: center;"
                                                                                                             src="https://cdn.jsdelivr.net/gh/angular-material-extensions/select-country@master/assets/badge_made-in-germany.svg">
</p>