Country Flags Utility

A comprehensive utility library for working with countries, flag emojis, flag images, and generating country select dropdowns across various frameworks.

Features

• 🌍 Get a list of all countries with their ISO codes and flag emojis
• 🏳️ Convert country codes to flag emojis
• 🖼️ Generate flag image URLs using flagcdn.com
• 📋 Create country select dropdowns with flags (emoji or images)
• ⚛️ Framework support for React, Angular, and vanilla JavaScript
• 🎨 Customizable display options and styling

Installation

1npm install country-flags-util

Table of Contents

• Basic Usage
• API Reference
  • Core Functions
  • Framework-specific Functions
• Examples
  • React Example
  • Angular Example
  • Vanilla JavaScript Example
• Browser Support
• Contributing
• License

Basic Usage

1const { 
2  getAllCountries, 
3  getFlagEmoji, 
4  getFlagImageUrl, 
5  getCountrySelect 
6} = require('country-flags-util');
7
8// Get all countries with their flags
9const countries = getAllCountries();
10console.log(countries[0]); // { name: "Afghanistan", code: "AF", flag: "🇦🇫" }
11
12// Get flag emoji for a specific country code
13const usFlag = getFlagEmoji('US');
14console.log(usFlag); // 🇺🇸
15
16// Get flag image URL from flagcdn.com
17const ukFlagUrl = getFlagImageUrl('GB', 80);
18console.log(ukFlagUrl); // https://flagcdn.com/w80/gb.png
19
20// Generate HTML for a country select dropdown with image flags (default)
21const selectHTML = getCountrySelect({
22  id: 'my-countries',
23  name: 'country-selector',
24  className: 'form-control',
25  selectedCode: 'CA'
26});
27
28// Generate HTML for a country select dropdown with emoji flags
29const emojiSelectHTML = getCountrySelect({
30  selectedCode: 'JP',
31  useImageFlags: false
32});

API Reference

Core Functions

getAllCountries()

Returns an array of objects containing country information.

Returns:

• Array<Object>: Array of country objects with the following properties:
  • name (String): The country name
  • code (String): The 2-letter ISO country code
  • flag (String): The emoji flag for the country

Example:

1const countries = getAllCountries();
2// [
3//   { name: "Afghanistan", code: "AF", flag: "🇦🇫" },
4//   { name: "Åland Islands", code: "AX", flag: "🇦🇽" },
5//   ...
6// ]

getFlagEmoji(code)

Converts a 2-letter ISO country code to an emoji flag.

Parameters:

• code (String): The 2-letter ISO country code (e.g., "US", "IN")

Returns:

• String: The flag emoji or an empty string if the code is invalid

Example:

1const flag = getFlagEmoji('JP');
2console.log(flag); // 🇯🇵

getFlagImageUrl(code, width)

Gets the flag image URL from flagcdn.com.

Parameters:

• code (String): The 2-letter ISO country code (e.g., "US", "IN")
• width (Number, optional): The width of the flag image in pixels (default: 40)

Returns:

• String: URL to the flag image or an empty string if the code is invalid

Example:

1const flagUrl = getFlagImageUrl('DE', 80);
2console.log(flagUrl); // https://flagcdn.com/w80/de.png

getCountrySelect(options)

Generates HTML for a select dropdown with country flags and names.

Parameters:

• options (Object, optional): Configuration object with the following properties:
  • id (String): HTML id attribute for the select element (default: 'country-select')
  • name (String): HTML name attribute for the select element (default: 'country')
  • className (String): HTML class attribute for the select element (default: '')
  • selectedCode (String): Country code to be selected by default (default: '')
  • useImageFlags (Boolean): Whether to use image flags instead of emoji flags (default: true)
  • flagWidth (Number): Width of flag images in pixels (default: 40)

Returns:

• String: HTML string for the country select dropdown

Example:

1const html = getCountrySelect({
2  id: 'my-country-select',
3  className: 'form-control',
4  selectedCode: 'FR',
5  useImageFlags: true,
6  flagWidth: 30
7});

Framework-specific Functions

React

The React module provides functions to generate JSX code and full React components.

1const { react, getAllCountries } = require('country-flags-util');
2
3// Generate JSX code for a React select component
4const jsxCode = react.getReactCountrySelect(getAllCountries(), {
5  id: 'react-country-select',
6  onChange: 'handleCountryChange',
7  defaultValue: 'CA',
8  useImageFlags: true,
9  flagWidth: 30
10});
11
12// Generate a complete React component
13const componentCode = react.getReactCountryComponent('CountrySelector');

Angular

The Angular module provides functions to generate template code and full Angular components.

1const { angular, getAllCountries } = require('country-flags-util');
2
3// Generate Angular template code
4const templateCode = angular.getAngularCountrySelect(getAllCountries(), {
5  id: 'angular-country-select',
6  ngModel: 'selectedCountry',
7  useImageFlags: true,
8  flagWidth: 25
9});
10
11// Generate a complete Angular component with module
12const { component, module, usage } = angular.getAngularCountryComponent(true);

Vanilla JavaScript

The Vanilla JS module provides functions to generate JavaScript code for plain web applications.

1const { vanilla } = require('country-flags-util');
2
3// Generate vanilla JS code
4const jsCode = vanilla.getVanillaJsCode({
5  containerId: 'country-container',
6  selectId: 'vanilla-country-select',
7  selectClass: 'form-select',
8  selectedCode: 'AU',
9  useImageFlags: true,
10  flagWidth: 30
11});
12
13// Generate complete HTML & JS implementation
14const { html, js } = vanilla.getVanillaImplementation({
15  containerId: 'country-container',
16  selectId: 'country-select'
17});

Examples

React Example

1// Using the generated component
2import React from 'react';
3import { CountrySelect } from 'country-flags-util/react';
4
5function App() {
6  const handleCountryChange = (e) => {
7    console.log('Selected country:', e.target.value);
8  };
9
10  return (
11    <div className="App">
12      <h1>Country Selector</h1>
13      <CountrySelect 
14        id="country-selector"
15        className="form-select"
16        defaultValue="US"
17        onChange={handleCountryChange}
18        useImageFlags={true}
19        flagWidth={30}
20      />
21    </div>
22  );
23}
24
25export default App;

Angular Example

1// country.component.ts
2import { Component } from '@angular/core';
3import { getAllCountries, getFlagImageUrl } from 'country-flags-util';
4
5@Component({
6  selector: 'app-country-selector',
7  template: `
8    <select [(ngModel)]="selectedCountry" (ngModelChange)="onCountryChange($event)" class="form-control">
9      <option *ngFor="let country of countries" [value]="country.code">
10        <img [src]="getFlagUrl(country.code)" [alt]="country.name" style="width: 30px; margin-right: 5px;">
11        {{ country.name }}
12      </option>
13    </select>
14  `
15})
16export class CountrySelectorComponent {
17  countries = getAllCountries();
18  selectedCountry = 'US';
19  
20  getFlagUrl(code: string): string {
21    return getFlagImageUrl(code, 30);
22  }
23  
24  onCountryChange(countryCode: string): void {
25    console.log('Selected country:', countryCode);
26  }
27}

Vanilla JavaScript Example

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <title>Country Selector Example</title>
6  <script src="node_modules/country-flags-util/index.js"></script>
7  <script>
8    document.addEventListener('DOMContentLoaded', function() {
9      const container = document.getElementById('country-container');
10      const { getAllCountries, getFlagImageUrl } = countryFlagsUtil;
11      
12      const countrySelect = document.createElement('select');
13      countrySelect.id = 'country-select';
14      countrySelect.className = 'form-select';
15      
16      getAllCountries().forEach(function(country) {
17        const option = document.createElement('option');
18        option.value = country.code;
19        
20        const flagImg = document.createElement('img');
21        flagImg.src = getFlagImageUrl(country.code, 30);
22        flagImg.alt = country.code;
23        flagImg.style.width = '30px';
24        flagImg.style.marginRight = '5px';
25        flagImg.style.verticalAlign = 'middle';
26        
27        option.appendChild(flagImg);
28        option.appendChild(document.createTextNode(country.name));
29        
30        if(country.code === 'US') {
31          option.selected = true;
32        }
33        
34        countrySelect.appendChild(option);
35      });
36      
37      countrySelect.addEventListener('change', function(e) {
38        console.log('Selected country:', e.target.value);
39      });
40      
41      container.appendChild(countrySelect);
42    });
43  </script>
44</head>
45<body>
46  <h1>Country Selector</h1>
47  <div id="country-container"></div>
48</body>
49</html>

Browser Support

This library uses Unicode flag emojis which are supported in most modern browsers. Image flags using flagcdn.com are supported across all browsers.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

---

Made with ❤️ by Nabarup Roy