Country List with Dial Code and Flag

https://zin-kyaw-kyaw.gitbook.io/country-flags/
Admin
A package that provides a comprehensive list of countries with their flag emojis, flag SVGs, and...
Tokens:2,971
Snippets:15
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Country List Package via NPM

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/installation

Installs the 'country-list-with-dial-code-and-flag' package using the Node Package Manager (NPM). This is the recommended method for projects using Node.js or build tools.

```sh
npm install country-list-with-dial-code-and-flag
```

--------------------------------

### Display Country Flag SVG using JavaScript

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/installation

Demonstrates how to fetch country data and display its corresponding SVG flag in an HTML element. This requires both the main library and the country-flag-svg script to be included.

```html
<div id="flag"></div>
<script>
  const mm = window.CountryList.findOneByCountryCode('mm')
  document.getElementById('flag').innerHTML = window.CountryFlagSvg[mm.code]
</script>
```

--------------------------------

### Include Country List Package via CDN

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/installation

Includes the 'country-list-with-dial-code-and-flag' package directly into an HTML document using a Content Delivery Network (CDN). This method is suitable for static websites or quick integrations.

```html
<script src="https://cdn.jsdelivr.net/npm/country-list-with-dial-code-and-flag/dist/main.js"></script>
```

--------------------------------

### Include Country Flag SVG Script via CDN

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/installation

Includes an optional script for country flag SVGs from a CDN. This script provides access to SVG representations of country flags, which can be dynamically displayed.

```html
<script src="https://cdn.jsdelivr.net/npm/country-list-with-dial-code-and-flag/dist/country-flag-svg.js"></script>
```

--------------------------------

### Get All Country Data

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Retrieves an array of all available country objects. Each object contains details like country name, dial code, ISO code, and flag emoji. This function is a primary way to access the complete dataset.

```javascript
import CountryList from 'country-list-with-dial-code-and-flag'

CountryList.getAll()
// Response => Array<Country>
```

--------------------------------

### Phone Number Formatting

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Details on how to format phone numbers using the library and google-libphonenumber.

```APIDOC
## Phone Number Formatting

### Description
Formats phone numbers according to various international standards using the `google-libphonenumber` library.

### Setup

Install the necessary packages:
```bash
npm install google-libphonenumber
npm install --save-dev @types/google-libphonenumber # Required for TypeScript
```

### Initialization (Version 5.0+)

For versions 5.0 and later, you must explicitly set the `PhoneNumberUtil` instance:

```javascript
import CountryList, { PhoneNumberFormat } from 'country-list-with-dial-code-and-flag';
import { PhoneNumberUtil } from 'google-libphonenumber';

CountryList.setPhoneNumberUtil(PhoneNumberUtil.getInstance());
```

### Usage

Use the `formatPhoneNumber` method on a country object obtained via `findOneByCountryCode()`.

#### `formatPhoneNumber(phoneNumber: string, format?: PhoneNumberFormat)`

- **Description**: Formats the given phone number.
- **Parameters**:
  - `phoneNumber` (string) - The phone number to format. Can be local or international format.
  - `format` (PhoneNumberFormat) - Optional - The desired output format. Defaults to E.164 if not specified.
- **Returns**: `string` - The formatted phone number.

**Available `PhoneNumberFormat` values:**
- `PhoneNumberFormat.E164`
- `PhoneNumberFormat.INTERNATIONAL`
- `PhoneNumberFormat.NATIONAL`
- `PhoneNumberFormat.RFC3966`

### Request Example (Basic Formatting)

```javascript
import CountryList from 'country-list-with-dial-code-and-flag';

// Ensure PhoneNumberUtil is set if using v5.0+
// import { PhoneNumberUtil } from 'google-libphonenumber';
// CountryList.setPhoneNumberUtil(PhoneNumberUtil.getInstance());

const mm = CountryList.findOneByCountryCode('mm');
if (mm) {
  console.log(mm.formatPhoneNumber('0888888888'));       // Output: +95888888888
  console.log(mm.formatPhoneNumber('+95888888888'));     // Output: +95888888888
  console.log(mm.formatPhoneNumber('888888888'));        // Output: +95888888888
  console.log(mm.formatPhoneNumber('088-888-888-8'));   // Output: +95888888888
}
```

### Request Example (Specific Formats)

```javascript
import CountryList, { PhoneNumberFormat } from 'country-list-with-dial-code-and-flag';

// Ensure PhoneNumberUtil is set if using v5.0+
// import { PhoneNumberUtil } from 'google-libphonenumber';
// CountryList.setPhoneNumberUtil(PhoneNumberUtil.getInstance());

const us = CountryList.findOneByCountryCode('us');
if (us) {
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.E164)); 
  // Output: +12124567890
  
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.INTERNATIONAL)); 
  // Output: +1 212-456-7890
  
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.NATIONAL)); 
  // Output: (212) 456-7890
  
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.RFC3966)); 
  // Output: tel:+1-212-456-7890
}
```

### Note

The `formatPhoneNumber()` function relies on the `google-libphonenumber` package. For detailed information, refer to the [official documentation](https://www.npmjs.com/package/google-libphonenumber).
```

--------------------------------

### Format Phone Numbers with Specific Formats

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Shows how to format a phone number using different `PhoneNumberFormat` options provided by `google-libphonenumber`. This allows displaying numbers in E.164, INTERNATIONAL, NATIONAL, or RFC3966 formats, catering to various display requirements.

```javascript
const us = CountryList.findOneByCountryCode('us')
if (us) {
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.E164))
  // +12124567890
  
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.INTERNATIONAL))
  // +1 212-456-7890
  
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.NATIONAL))
  // (212) 456-7890
  
  console.log(us.formatPhoneNumber('2124567890', PhoneNumberFormat.RFC3966))
  // tel:+1-212-456-7890
}
```

--------------------------------

### Find Countries by Dial Code or Keyword

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Searches for countries based on their dial code or a keyword. `findByDialCode` can return multiple countries if a dial code is shared, while `findByKeyword` finds countries whose names match the provided string. Both return an array of country objects.

```javascript
import CountryList from 'country-list-with-dial-code-and-flag'

CountryList.findByDialCode('+95')
// Response => Array<Country>

CountryList.findByKeyword('united')
// Response => Array<Country>
```

--------------------------------

### Find Country by Code or Dial Code

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Allows searching for a specific country using its ISO 3166-1 alpha-2 country code or its international dial code. It returns a single country object if found. This is useful for looking up details for a known country identifier.

```javascript
import CountryList from 'country-list-with-dial-code-and-flag'

CountryList.findOneByCountryCode('MM')
// Response => Country

CountryList.findOneByDialCode('+95')
// Response => Country
```

--------------------------------

### Filter Country Search with Secondary Dial Codes

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Demonstrates how to use the `withSecondary` option when searching for countries by country code. Setting `withSecondary` to `false` returns only primary dial codes, while `true` (the default) includes secondary dial codes, potentially increasing the number of results.

```javascript
const listWithSecondary = CountryList.findByCountryCode('DO', { withSecondary: true })
console.log(listWithSecondary.length) // Example: 3

const listWithoutSecondary = CountryList.findByCountryCode('DO', { withSecondary: false })
console.log(listWithoutSecondary.length) // Example: 1
```

--------------------------------

### Format Phone Numbers with Google Libphonenumber

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Integrates with the `google-libphonenumber` library to format phone numbers. After setting the `PhoneNumberUtil` instance, country objects can format local or international numbers into various standard formats like E.164, INTERNATIONAL, NATIONAL, or RFC3966.

```javascript
import CountryList , { PhoneNumberFormat } from 'country-list-with-dial-code-and-flag'
import { PhoneNumberUtil } from 'google-libphonenumber'

CountryList.setPhoneNumberUtil(PhoneNumberUtil.getInstance())

const mm = CountryList.findOneByCountryCode('mm')
if (mm) {
  console.log(mm.formatPhoneNumber('0888888888')) // +95888888888
  console.log(mm.formatPhoneNumber('+95888888888')) // +95888888888
  console.log(mm.formatPhoneNumber('888888888')) // +95888888888
  console.log(mm.formatPhoneNumber('088-888-888-8')) // +95888888888
}
```

--------------------------------

### Generate Country Flag SVG

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

Provides a way to obtain the SVG string for a country's flag. This requires first finding the country data using `findOneByCountryCode` and then accessing the corresponding SVG from the `CountryFlagSvg` object. This is useful for displaying flags in UI elements.

```javascript
import CountryList from 'country-list-with-dial-code-and-flag'
import CountryFlagSvg from 'country-list-with-dial-code-and-flag/dist/flag-svg'

const myanmar = CountryList.findOneByCountryCode('mm')
if (myanmar) {
  const flagSvg = CountryFlagSvg[myanmar.code]
  console.log(flagSvg) // This will return svg string
}
```

--------------------------------

### Country List API

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

This section details the primary functions for retrieving and searching country data.

```APIDOC
## Country List API

### Description
Provides functions to retrieve and search for country information, including names, dial codes, country codes, and flag emojis.

### Methods

#### `getAll()`

- **Description**: Retrieves a list of all available countries.
- **Returns**: `Array<Country>`

#### `findOneByCountryCode(code: string)`

- **Description**: Finds a single country by its ISO 3166-1 alpha-2 country code.
- **Parameters**:
  - `code` (string) - Required - The 2-letter country code (e.g., 'MM').
- **Returns**: `Country | undefined`

#### `findByCountryCode(code: string, options?: { withSecondary: boolean })`

- **Description**: Finds countries by their ISO 3166-1 alpha-2 country code. Supports filtering for secondary dial codes.
- **Parameters**:
  - `code` (string) - Required - The 2-letter country code (e.g., 'DO').
  - `options` (object) - Optional - Configuration for secondary dial codes. Defaults to `{ withSecondary: true }`.
    - `withSecondary` (boolean) - Optional - Whether to include secondary dial codes.
- **Returns**: `Array<Country>`

#### `findOneByDialCode(dialCode: string)`

- **Description**: Finds a single country by its international dial code.
- **Parameters**:
  - `dialCode` (string) - Required - The dial code (e.g., '+95').
- **Returns**: `Country | undefined`

#### `findByDialCode(dialCode: string)`

- **Description**: Finds all countries associated with a given dial code.
- **Parameters**:
  - `dialCode` (string) - Required - The dial code (e.g., '+95').
- **Returns**: `Array<Country>`

#### `findByKeyword(keyword: string, options?: { withSecondary: boolean })`

- **Description**: Finds countries whose names contain the specified keyword. Supports filtering for secondary dial codes.
- **Parameters**:
  - `keyword` (string) - Required - The search term (e.g., 'united').
  - `options` (object) - Optional - Configuration for secondary dial codes. Defaults to `{ withSecondary: true }`.
    - `withSecondary` (boolean) - Optional - Whether to include secondary dial codes.
- **Returns**: `Array<Country>`

#### `groupCountriesByFirstLetter()`

- **Description**: Groups all available countries by the first letter of their name.
- **Returns**: `Object` (where keys are letters and values are arrays of countries)

### Country Object Structure

- `name` (string): The name of the country.
- `dial_code` (string): The primary international dial code.
- `code` (string): The ISO 3166-1 alpha-2 country code.
- `flag` (string): The country's flag emoji.
- `preferred` (boolean): Indicates if this is a preferred dial code for the country.

### Request Example (getAll)

```javascript
import CountryList from 'country-list-with-dial-code-and-flag';

const allCountries = CountryList.getAll();
console.log(allCountries);
```

### Response Example (getAll)

```json
[
  { "name": "Afghanistan", "dial_code": "+93", "code": "AF", "flag": "🇦🇫" },
  { "name": "Myanmar", "dial_code": "+95", "code": "MM", "flag": "🇲🇲" }
]
```
```

--------------------------------

### Country Flag SVG

Source: https://zin-kyaw-kyaw.gitbook.io/country-flags/usage

How to retrieve SVG string representations of country flags.

```APIDOC
## Country Flag SVG

### Description
Accesses SVG string data for country flags using their country codes.

### Usage

1. Find a country object using `findOneByCountryCode()`.
2. Access the SVG string from the `CountryFlagSvg` object using the country's code.

### Request Example

```javascript
import CountryList from 'country-list-with-dial-code-and-flag';
import CountryFlagSvg from 'country-list-with-dial-code-and-flag/dist/flag-svg';

const myanmar = CountryList.findOneByCountryCode('mm');
if (myanmar) {
  const flagSvg = CountryFlagSvg[myanmar.code];
  console.log(flagSvg); // This will return the SVG string
}
```
```
Tokens:
Raw