🌎 Country Code with Flag

An ultra-lightweight, zero-dependency NPM package to get comprehensive country data, including dial codes and CDN-hosted SVG flags.

🚀 Key Features

• ⚡ Fast Installation: Only ~50KB (flags are hosted on CDN to keep your bundle small).
• 📦 Zero Dependencies: Pure JavaScript, no overhead.
• 🌍 240+ Countries: Comprehensive list of countries and territories.
• 🚩 SVG Flags: High-quality SVG flags via jsDelivr CDN.
• 📱 Phone Support: Includes international dial codes for all countries.
• 🔍 Easy Search: Robust search and filtering functions.
• 🛡️ TypeScript Ready: Full type definitions included.

📦 Installation

Choose your favorite package manager:

# npm
npm install country-code-with-flag

# yarn
yarn add country-code-with-flag

# pnpm
pnpm add country-code-with-flag

💡 Quick Start

const { getCountryByCode } = require('country-code-with-flag');

const country = getCountryByCode('IN');
console.log(country);
/*
{
  name: "India",
  code: "IN",
  dialCode: "+91",
  flag: ".../flags/in.svg"
}
*/

🛠️ Detailed Usage Examples

1. In a React/Next.js Component

Perfect for creating country pickers or phone input fields.

import React from 'react';
import { getAllCountries, Country } from 'country-code-with-flag';

const CountryList = () => {
  const countries: Country[] = getAllCountries();

  return (
    <div className="country-grid">
      {countries.map((c) => (
        <div key={c.code} className="country-card">
          <img src={c.flag} alt={c.name} width="30" />
          <span>{c.name} ({c.dialCode})</span>
        </div>
      ))}
    </div>
  );
};

2. Powerful Search Functionality

Use searchCountries to filter results dynamically.

const { searchCountries } = require('country-code-with-flag');

// Search by name, dial code, or ISO code
const results = searchCountries('uni'); 
// Returns United Kingdom, United States, United Arab Emirates, etc.

const dialResults = searchCountries('+44');
// Returns United Kingdom

3. Phone Number Length Validation

Validate if a phone number matches the expected length for a specific country. You can also bypass this validation or provide your own custom logic.

const { validatePhoneLength } = require('country-code-with-flag');

// Standard validation
const result = validatePhoneLength('9999999999', 'IN'); 
// { isValid: true, message: null }

const invalidResult = validatePhoneLength('123', 'IN'); 
// { isValid: false, message: 'Invalid phone length for IN. Expected 10 digits, but got 3.' }

// Bypass built-in validation
const bypassed = validatePhoneLength('123', 'IN', { bypass: true }); 
// { isValid: true, message: null }

// Custom validation message
const customMsg = validatePhoneLength('123', 'IN', { customMessage: 'Must be 10 digits!' });
// { isValid: false, message: 'Must be 10 digits!' }

// Custom validation logic
const customLogic = validatePhoneLength('12345', 'IN', { 
  customValidator: (phone, code) => phone.length === 5 
}); 
// { isValid: true, message: null }

📚 API Reference

| Method | Parameters | Returns | Description | | :--- | :--- | :--- | :--- | | getAllCountries() | None | Country[] | Returns all 240+ country objects. | | getCountryByCode(code) | string | Country \| undefined | Find country by ISO alpha-2 code (e.g., 'US'). | | getCountryByDialCode(dial) | string | Country \| undefined | Find country by dial code (e.g., '+91'). | | getCountryByName(name) | string | Country \| undefined | Find country by its full name. | | searchCountries(query) | string | Country[] | Returns matches by name, code, or dial code. | | validatePhoneLength(phone, code, options?) | string, string, object | ValidationResult | Validate phone length. Returns { isValid, message }. Supports bypass, customMessage, and customValidator. |

💻 Supported Node.js Versions

This package is tested and supported on the following Node.js versions:

• Node.js 14.x (LTS)
• Node.js 16.x (LTS)
• Node.js 18.x (LTS)
• Node.js 20.x (Current)
• Node.js 22.x (Current)

🤝 Collaboration & Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📜 License

Distributed under the MIT License. See LICENSE for more information.

👥 Collaborators

• patelprakash - Initial work & Lead Developer - @patelprakash

⭐ Support

If you find this package useful, please give it a star on GitHub! It helps others find the project.