country-x

A blazing-fast, lightweight, and tree-shakable utility for international country data, including ISO codes, phone formats, flags, currencies, and fuzzy search.

Why country-x?

• 🚀 Blazing Fast: All lookups are O(1) time complexity using pre-computed hash maps. No more slow array searches.
• 🌲 Tree-shakable: Core logic and React components are separate. Only import what you need, keeping your bundle size minimal.
• 💡 Smart Search: Built-in, zero-dependency fuzzy search to find countries even with typos.
• 📞 Advanced Phone Handling: Format phone numbers to local standards and validate them.
• 🇦🇺 Flags & More: Includes currency data, timezones, and a ready-to-use React <Flag /> component.
• 🔒 Fully Typed: Written entirely in TypeScript for a great developer experience.

Installation

npm install country-x
# or
yarn add country-x

If using React components, make sure react is installed in your project.

API

Core Utilities

Import core functions directly from country-x.

import { getCountryByIso, searchCountries, formatPhoneNumber } from 'country-x';

// O(1) Lookup
const pakistan = getCountryByIso('PK');
console.log(pakistan.currency.code); // PKR

// Fuzzy Search
const results = searchCountries('pakitan'); // notice the typo
console.log(results[0].name); // 'Pakistan'

// Phone Formatting
const formatted = formatPhoneNumber('3121234567', 'PK');
console.log(formatted); // 312-1234567

• getAllCountries(): Country[]
• getCountryByIso(iso: string): Country | undefined
• getCountryByCode(code: string): Country | undefined
• getCountryByName(name: string): Country | undefined
• searchCountries(query: string): Country[]
• formatPhoneNumber(phone: string, isoOrCode: string): string
• isValidPhoneNumber(phone: string, isoOrCode: string): boolean

React Hooks & Components

Import React-specific utilities from country-x/react.

import React, { useState } from 'react';
import { useCountry, Flag } from 'country-x/react';

function CountryPicker() {
  const [query, setQuery] = useState('');
  const { countries } = useCountry({ searchQuery: query });

  return (
    <div>
      <input 
        type="text" 
        value={query} 
        onChange={(e) => setQuery(e.target.value)} 
        placeholder="Search for a country..."
      />
      <ul>
        {countries.slice(0, 5).map(country => (
          <li key={country.iso2}>
            <Flag iso2={country.iso2} size={20} style={{ marginRight: '8px' }} />
            {country.name} ({country.callingCode})
          </li>
        ))}
      </ul>
    </div>
  );
}

• useCountry({ searchQuery: string }): Hook to get a list of countries, filtered by a search query.
• <Flag iso2={string} size={number} />: A simple, efficient component to display a country's flag.

Build

To build the package from source:

npm install
npm run build

This generates the dist folder with CJS, ESM, and TypeScript declaration files.