🌍 Countries Cities AR

Countries and cities dataset for the whole world with Arabic, English, and French names. Includes ISO country codes and administrative divisions (states/provinces/governorates). Optimized for React/Next.js/Vue and TypeScript projects.

Complete library of 250 world countries with 4,642 states/provinces in 3 languages (Arabic, English, French)

📖 Documentation • 🚀 Live Demo • 📦 npm Package • 🐛 Report Bug

🔹 Quick Usage (TL;DR)

Works with both ESM and CommonJS.

ESM

import {
  allCountries,
  getCountryByCode,
  getCitiesByCountryCode,
  getCountryName,
  searchCountries,
  searchCities,
  type Country,
  type City,
} from 'countries-cities-ar';

console.log(allCountries.length); // 250
const egypt = getCountryByCode('EG');
const egyptCities = getCitiesByCountryCode('EG');

CommonJS

const {
  allCountries,
  getCountryByCode,
  getCitiesByCountryCode,
  getCountryName,
  searchCountries,
  searchCities,
} = require('countries-cities-ar');

Named Exports (complete list)

// Types
// Country, City, Language

// Data
// allCountries, africaCountries, asiaCountries, europeCountries, americasCountries, oceaniaCountries

// Helpers
// getCountryByCode, getCitiesByCountryCode, getCountryName, searchCountries, searchCities

✨ Features

📦 Installation

# npm
npm install countries-cities-ar

# yarn
yarn add countries-cities-ar

# pnpm
pnpm add countries-cities-ar

# bun
bun add countries-cities-ar

Requirements

• Node.js 16+ or Bun 1.0+
• TypeScript 5+ (optional, but recommended)
• Works with: React, Next.js, Vue, Express, or any JavaScript project

🚀 Quick Start

1. Install the Package

npm install countries-cities-ar

2. Import and Use

import { allCountries, getCountryByCode } from 'countries-cities-ar';

// Get all 250 countries
console.log(allCountries.length); // 250

// Get a specific country
const egypt = getCountryByCode('EG');
console.log(egypt.nameAr); // "مصر"
console.log(egypt.cities.length); // 27 governorates

📚 Complete Usage Guide

Basic Usage

import { allCountries, getCountryByCode, searchCountries } from 'countries-cities-ar';

// Access all 250 countries
console.log(allCountries.length); // 250

// Get a specific country with all its states/governorates
const egypt = getCountryByCode('EG');
console.log(egypt);
// {
//   code: 'EG',
//   name: 'Egypt',
//   nameAr: 'مصر',
//   nameFr: 'Égypte',
//   cities: [
//     { name: 'Cairo', nameAr: 'القاهرة', nameFr: 'Le Caire' },
//     { name: 'Alexandria', nameAr: 'الإسكندرية', nameFr: 'Alexandrie' },
//     { name: 'Giza', nameAr: 'الجيزة', nameFr: 'Gizeh' },
//     // ... 24 more governorates (27 total)
//   ]
// }

// Get Saudi Arabia with all 13 regions
const saudi = getCountryByCode('SA');
console.log(saudi.cities.length); // 13
console.log(saudi.cities[0]);
// { name: 'Riyadh', nameAr: 'الرياض', nameFr: 'Riyad' }

// Get UAE with all 7 emirates
const uae = getCountryByCode('AE');
console.log(uae.cities); // All 7 emirates with Arabic names

// Search for countries in any language
const arabCountries = searchCountries('عرب', 'ar'); // Search in Arabic
const europeCountries = searchCountries('united', 'en'); // Search in English

Working with Cities/States

import { getCitiesByCountryCode, searchCities } from 'countries-cities-ar';

// Get all states for a country
const usStates = getCitiesByCountryCode('US'); // 57 states
const chinaCities = getCitiesByCountryCode('CN'); // 31 provinces
const indiaStates = getCitiesByCountryCode('IN'); // 36 states

// Search for cities/states globally
const allCairo = searchCities('cairo', undefined, 'en');
// Finds Cairo in Egypt and other countries

// Search cities in a specific country
const egyptCities = searchCities('القاهرة', 'EG', 'ar');
console.log(egyptCities[0]);
// {
//   city: { name: 'Cairo', nameAr: 'القاهرة', nameFr: 'Le Caire' },
//   country: { code: 'EG', name: 'Egypt', nameAr: 'مصر', ... }
// }

// Search in French
const parisCities = searchCities('paris', 'FR', 'fr');

CommonJS

const { 
  getCountryByCode, 
  getCitiesByCountryCode,
  getCountryName,
  searchCountries,
  searchCities 
} = require('countries-cities-ar');

const uae = getCountryByCode('AE');
console.log(uae.name); // "United Arab Emirates"
console.log(uae.nameAr); // "الإمارات العربية المتحدة"

const cities = getCitiesByCountryCode('AE');
cities.forEach(city => {
  console.log(`${city.name} - ${city.nameAr}`);
});

API Reference

Types

interface City {
  name: string;      // English name
  nameAr: string;    // Arabic name
  nameFr: string;    // French name
}

interface Country {
  code: string;      // ISO country code (e.g., "EG", "SA")
  name: string;      // English name
  nameAr: string;    // Arabic name
  nameFr: string;    // French name
  cities: City[];    // Array of cities, governorates, states, provinces
}

type Language = 'en' | 'ar' | 'fr';

Functions

getCountryByCode(code: string): Country | undefined

Get a country by its ISO code.

const country = getCountryByCode('EG');
// Returns: { code: 'EG', name: 'Egypt', nameAr: 'مصر', cities: [...] }

getCitiesByCountryCode(code: string): City[]

Get all cities for a specific country.

const cities = getCitiesByCountryCode('SA');
// Returns: [{ name: 'Riyadh', nameAr: 'الرياض' }, ...]

getCountryName(code: string, lang?: Language): string | undefined

Get the country name in the specified language.

const nameEn = getCountryName('EG', 'en'); // "Egypt"
const nameAr = getCountryName('EG', 'ar'); // "مصر"
const nameFr = getCountryName('EG', 'fr'); // "Égypte"
const nameDefault = getCountryName('EG');  // "Egypt" (defaults to 'en')

searchCountries(query: string, lang?: Language): Country[]

Search for countries by name.

// Search in English
const results = searchCountries('united', 'en');

// Search in Arabic
const resultsAr = searchCountries('العربية', 'ar');

// Search in French
const resultsFr = searchCountries('france', 'fr');

// Default language is English
const defaultResults = searchCountries('states');

searchCities(query: string, countryCode?: string, lang?: Language): Array<{ city: City; country: Country }>

Search for cities by name, optionally filtered by country.

// Search all cities
const allResults = searchCities('alex', undefined, 'en');

// Search cities in specific country
const egyptResults = searchCities('alex', 'EG', 'en');

// Search in Arabic
const arabicResults = searchCities('القاهرة', undefined, 'ar');

// Search in French
const frenchResults = searchCities('paris', undefined, 'fr');

Data Exports

import {
  allCountries,        // All countries from all continents
  africaCountries,     // African countries only
  asiaCountries,       // Asian countries only
  europeCountries,     // European countries only
  americasCountries,   // American countries only
  oceaniaCountries,    // Oceanian countries only
} from 'countries-cities-ar';

Examples

React Example - Country & City Selector

import React, { useState, useMemo } from 'react';
import { allCountries, type Country, type City } from 'countries-cities-ar';

function CountryCitySelector() {
  const [selectedCountry, setSelectedCountry] = useState<Country | null>(null);
  const [selectedCity, setSelectedCity] = useState<City | null>(null);
  const [language, setLanguage] = useState<'ar' | 'en' | 'fr'>('ar');
  const [search, setSearch] = useState('');

  // Filter countries based on search
  const filteredCountries = useMemo(() => {
    if (!search) return allCountries;
    return allCountries.filter(country => {
      const name = language === 'ar' ? country.nameAr : 
                   language === 'fr' ? country.nameFr : country.name;
      return name.toLowerCase().includes(search.toLowerCase());
    });
  }, [search, language]);

  const getCountryName = (country: Country) => {
    return language === 'ar' ? country.nameAr :
           language === 'fr' ? country.nameFr : country.name;
  };

  const getCityName = (city: City) => {
    return language === 'ar' && city.nameAr ? city.nameAr :
           language === 'fr' && city.nameFr ? city.nameFr : city.name;
  };

  return (
    <div className="p-6">
      {/* Language Selector */}
      <div className="mb-4">
        <button onClick={() => setLanguage('ar')}>🇸🇦 العربية</button>
        <button onClick={() => setLanguage('en')}>🇬🇧 English</button>
        <button onClick={() => setLanguage('fr')}>🇫🇷 Français</button>
      </div>

      {/* Country Search */}
      <input
        type="text"
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder={language === 'ar' ? 'ابحث عن دولة...' : 'Search country...'}
        className="w-full p-2 border rounded mb-4"
      />

      {/* Countries List */}
      <div className="grid grid-cols-2 gap-2 mb-6">
        {filteredCountries.slice(0, 20).map((country) => (
          <button
            key={country.code}
            onClick={() => {
              setSelectedCountry(country);
              setSelectedCity(null);
            }}
            className="p-3 border rounded hover:bg-blue-50"
          >
            {getCountryName(country)}
            <span className="text-xs text-gray-500 block">
              {country.cities.length} {language === 'ar' ? 'محافظة' : 'states'}
            </span>
          </button>
        ))}
      </div>

      {/* Cities/States List */}
      {selectedCountry && (
        <div>
          <h3 className="text-xl font-bold mb-3">
            {getCountryName(selectedCountry)} - {selectedCountry.cities.length} {language === 'ar' ? 'محافظة' : 'states'}
          </h3>
          <div className="grid grid-cols-3 gap-2">
            {selectedCountry.cities.map((city, idx) => (
              <button
                key={idx}
                onClick={() => setSelectedCity(city)}
                className="p-2 border rounded hover:bg-green-50 text-sm"
              >
                {getCityName(city)}
              </button>
            ))}
          </div>
        </div>
      )}

      {/* Selected Info */}
      {selectedCity && (
        <div className="mt-4 p-4 bg-gray-100 rounded">
          <strong>{language === 'ar' ? 'الاختيار:' : 'Selected:'}</strong>
          <p>{getCountryName(selectedCountry!)} - {getCityName(selectedCity)}</p>
        </div>
      )}
    </div>
  );
}

export default CountryCitySelector;

Next.js App Router Example

// app/page.tsx
import { allCountries } from 'countries-cities-ar';
import CountrySelector from '@/components/CountrySelector';

export default function Home() {
  return (
    <main className="container mx-auto p-8">
      <h1 className="text-4xl font-bold mb-6">🌍 دول ومدن العالم</h1>
      <p className="mb-4">250 دولة • 4,642 محافظة/ولاية • 3 لغات</p>
      <CountrySelector countries={allCountries} />
    </main>
  );
}

// components/CountrySelector.tsx (Client Component)
'use client';
import { useState } from 'react';
import type { Country } from 'countries-cities-ar';

interface Props {
  countries: Country[];
}

export default function CountrySelector({ countries }: Props) {
  const [selected, setSelected] = useState<Country | null>(null);
  
  return (
    <div>
      {/* Your UI here */}
      <p>Total countries: {countries.length}</p>
      {selected && (
        <div>
          <h2>{selected.nameAr} - {selected.name}</h2>
          <p>{selected.cities.length} محافظة</p>
        </div>
      )}
    </div>
  );
}

🛠️ Setup Guides

Next.js Setup (Step-by-Step)

Step 1: Create Next.js Project

# Create a new Next.js project
npx create-next-app@latest my-countries-app

# Choose the following options:
# ✓ TypeScript: Yes
# ✓ ESLint: Yes
# ✓ Tailwind CSS: Yes (optional)
# ✓ App Router: Yes
# ✓ Turbopack: Yes (optional)

cd my-countries-app

Step 2: Install the Library

npm install countries-cities-ar

Step 3: Create a Server Component

Create app/countries/page.tsx:

import { allCountries, getCountryByCode } from 'countries-cities-ar';

export default function CountriesPage() {
  // Server component - can directly use the data
  const egypt = getCountryByCode('EG');
  const saudi = getCountryByCode('SA');
  
  return (
    <div className="p-8">
      <h1 className="text-3xl font-bold mb-6">
        🌍 Countries & Cities Library
      </h1>
      
      <div className="grid gap-4">
        <div className="border p-4 rounded">
          <h2 className="text-xl font-semibold">{egypt?.nameAr}</h2>
          <p>{egypt?.name}</p>
          <p className="text-sm text-gray-600">
            {egypt?.cities.length} governorates
          </p>
        </div>
        
        <div className="border p-4 rounded">
          <h2 className="text-xl font-semibold">{saudi?.nameAr}</h2>
          <p>{saudi?.name}</p>
          <p className="text-sm text-gray-600">
            {saudi?.cities.length} regions
          </p>
        </div>
      </div>
      
      <div className="mt-8">
        <h3 className="text-lg font-semibold mb-2">All Countries</h3>
        <p>Total: {allCountries.length} countries</p>
      </div>
    </div>
  );
}

Step 4: Create an Interactive Client Component

Create components/CountryCitySelector.tsx:

'use client';

import { useState, useMemo } from 'react';
import { allCountries, type Country, type City } from 'countries-cities-ar';

export default function CountryCitySelector() {
  const [selectedCountry, setSelectedCountry] = useState<Country | null>(null);
  const [search, setSearch] = useState('');
  const [language, setLanguage] = useState<'ar' | 'en' | 'fr'>('ar');

  const filteredCountries = useMemo(() => {
    if (!search) return allCountries;
    return allCountries.filter(country => {
      const name = language === 'ar' ? country.nameAr :
                   language === 'fr' ? country.nameFr : country.name;
      return name.toLowerCase().includes(search.toLowerCase());
    });
  }, [search, language]);

  return (
    <div className="space-y-4">
      {/* Language Selector */}
      <div className="flex gap-2">
        <button
          onClick={() => setLanguage('ar')}
          className={`px-4 py-2 rounded ${
            language === 'ar' ? 'bg-blue-600 text-white' : 'bg-gray-200'
          }`}
        >
          🇸🇦 العربية
        </button>
        <button
          onClick={() => setLanguage('en')}
          className={`px-4 py-2 rounded ${
            language === 'en' ? 'bg-blue-600 text-white' : 'bg-gray-200'
          }`}
        >
          🇬🇧 English
        </button>
        <button
          onClick={() => setLanguage('fr')}
          className={`px-4 py-2 rounded ${
            language === 'fr' ? 'bg-blue-600 text-white' : 'bg-gray-200'
          }`}
        >
          🇫🇷 Français
        </button>
      </div>

      {/* Search Input */}
      <input
        type="text"
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder={language === 'ar' ? 'ابحث عن دولة...' : 'Search country...'}
        className="w-full p-3 border rounded-lg"
      />

      {/* Countries Grid */}
      <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-3">
        {filteredCountries.slice(0, 20).map((country) => (
          <button
            key={country.code}
            onClick={() => setSelectedCountry(country)}
            className="p-3 border rounded-lg hover:bg-blue-50 text-left"
          >
            <div className="font-semibold">
              {language === 'ar' ? country.nameAr :
               language === 'fr' ? country.nameFr : country.name}
            </div>
            <div className="text-xs text-gray-500">
              {country.cities.length} {language === 'ar' ? 'محافظة' : 'states'}
            </div>
          </button>
        ))}
      </div>

      {/* Selected Country Details */}
      {selectedCountry && (
        <div className="mt-6 p-4 bg-gray-50 rounded-lg">
          <h3 className="text-xl font-bold mb-3">
            {language === 'ar' ? selectedCountry.nameAr :
             language === 'fr' ? selectedCountry.nameFr : selectedCountry.name}
          </h3>
          <p className="mb-3">
            {selectedCountry.cities.length} {language === 'ar' ? 'محافظة/ولاية' : 'states/provinces'}
          </p>
          
          <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
            {selectedCountry.cities.map((city, idx) => (
              <div key={idx} className="p-2 bg-white rounded border text-sm">
                {language === 'ar' && city.nameAr ? city.nameAr : city.name}
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}

Step 5: Use in Your Page

Update app/page.tsx:

import CountryCitySelector from '@/components/CountryCitySelector';

export default function Home() {
  return (
    <main className="container mx-auto p-8">
      <h1 className="text-4xl font-bold mb-2">🌍 دول ومدن العالم</h1>
      <p className="text-gray-600 mb-8">
        250 دولة • 4,642 محافظة • 3 لغات
      </p>
      <CountryCitySelector />
    </main>
  );
}

Step 6: Run Your App

npm run dev

Visit http://localhost:3000 to see your app!

React Setup (Vite)

Step 1: Create React Project

npm create vite@latest my-countries-app -- --template react-ts
cd my-countries-app

Step 2: Install Dependencies

npm install
npm install countries-cities-ar

Step 3: Create Component

Create src/CountrySelector.tsx:

import { useState } from 'react';
import { allCountries, searchCountries } from 'countries-cities-ar';

function CountrySelector() {
  const [search, setSearch] = useState('');
  const [results, setResults] = useState(allCountries);

  const handleSearch = (value: string) => {
    setSearch(value);
    if (!value) {
      setResults(allCountries);
    } else {
      setResults(searchCountries(value, 'ar'));
    }
  };

  return (
    <div>
      <h1>🌍 Countries & Cities</h1>
      <input
        type="text"
        value={search}
        onChange={(e) => handleSearch(e.target.value)}
        placeholder="ابحث عن دولة..."
      />
      <p>Found: {results.length} countries</p>
      <ul>
        {results.slice(0, 10).map((country) => (
          <li key={country.code}>
            {country.nameAr} - {country.name}
            <span> ({country.cities.length} states)</span>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default CountrySelector;

Step 4: Use in App

Update src/App.tsx:

import CountrySelector from './CountrySelector';

function App() {
  return (
    <div className="App">
      <CountrySelector />
    </div>
  );
}

export default App;

Step 5: Run

npm run dev

Vue Component

<template>
  <div>
    <input 
      v-model="query" 
      @input="handleSearch" 
      placeholder="ابحث عن مدينة..."
    />
    <ul>
      <li v-for="result in results" :key="result.city.name">
        {{ result.city.nameAr }} - {{ result.country.nameAr }}
      </li>
    </ul>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { searchCities } from 'countries-cities-ar';

const query = ref('');
const results = ref([]);

const handleSearch = () => {
  results.value = searchCities(query.value, undefined, 'ar');
};
</script>

🎯 Advanced Examples

Autocomplete Search with Debounce

import { useState, useEffect } from 'react';
import { searchCountries } from 'countries-cities-ar';

function CountryAutocomplete() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (!query) {
      setResults([]);
      return;
    }

    setLoading(true);
    const timer = setTimeout(() => {
      const searchResults = searchCountries(query, 'ar');
      setResults(searchResults);
      setLoading(false);
    }, 300); // Debounce 300ms

    return () => clearTimeout(timer);
  }, [query]);

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="ابحث عن دولة..."
      />
      {loading && <p>جاري البحث...</p>}
      <ul>
        {results.map((country) => (
          <li key={country.code}>
            {country.nameAr} - {country.cities.length} محافظة
          </li>
        ))}
      </ul>
    </div>
  );
}

Multi-language Dropdown

import { useState } from 'react';
import { allCountries, type Country } from 'countries-cities-ar';

function MultiLanguageDropdown() {
  const [lang, setLang] = useState<'ar' | 'en' | 'fr'>('ar');
  const [selected, setSelected] = useState<Country | null>(null);

  const getName = (country: Country) => {
    return lang === 'ar' ? country.nameAr :
           lang === 'fr' ? country.nameFr : country.name;
  };

  return (
    <div>
      {/* Language Toggle */}
      <select value={lang} onChange={(e) => setLang(e.target.value as any)}>
        <option value="ar">العربية</option>
        <option value="en">English</option>
        <option value="fr">Français</option>
      </select>

      {/* Country Dropdown */}
      <select onChange={(e) => {
        const country = allCountries.find(c => c.code === e.target.value);
        setSelected(country || null);
      }}>
        <option value="">اختر دولة...</option>
        {allCountries.map((country) => (
          <option key={country.code} value={country.code}>
            {getName(country)}
          </option>
        ))}
      </select>

      {/* Display Selected */}
      {selected && (
        <div>
          <h3>{getName(selected)}</h3>
          <p>{selected.cities.length} {lang === 'ar' ? 'محافظة' : 'states'}</p>
        </div>
      )}
    </div>
  );
}

Form with Country & City Selection

import { useState } from 'react';
import { allCountries, type Country, type City } from 'countries-cities-ar';

function AddressForm() {
  const [country, setCountry] = useState<Country | null>(null);
  const [city, setCity] = useState<City | null>(null);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    console.log({
      country: country?.name,
      city: city?.name,
      countryAr: country?.nameAr,
      cityAr: city?.nameAr,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Country Select */}
      <select onChange={(e) => {
        const selected = allCountries.find(c => c.code === e.target.value);
        setCountry(selected || null);
        setCity(null); // Reset city
      }}>
        <option value="">اختر الدولة</option>
        {allCountries.map((c) => (
          <option key={c.code} value={c.code}>{c.nameAr}</option>
        ))}
      </select>

      {/* City Select */}
      {country && (
        <select onChange={(e) => {
          const idx = parseInt(e.target.value);
          setCity(country.cities[idx] || null);
        }}>
          <option value="">اختر المحافظة</option>
          {country.cities.map((city, idx) => (
            <option key={idx} value={idx}>
              {city.nameAr || city.name}
            </option>
          ))}
        </select>
      )}

      <button type="submit" disabled={!country || !city}>
        إرسال
      </button>
    </form>
  );
}

Filter by Region/Continent

import { 
  africaCountries, 
  asiaCountries, 
  europeCountries,
  americasCountries,
  oceaniaCountries 
} from 'countries-cities-ar';

function RegionFilter() {
  const [region, setRegion] = useState('all');

  const getCountriesByRegion = () => {
    switch (region) {
      case 'africa': return africaCountries;
      case 'asia': return asiaCountries;
      case 'europe': return europeCountries;
      case 'americas': return americasCountries;
      case 'oceania': return oceaniaCountries;
      default: return allCountries;
    }
  };

  const countries = getCountriesByRegion();

  return (
    <div>
      <select value={region} onChange={(e) => setRegion(e.target.value)}>
        <option value="all">كل الدول ({allCountries.length})</option>
        <option value="africa">أفريقيا ({africaCountries.length})</option>
        <option value="asia">آسيا ({asiaCountries.length})</option>
        <option value="europe">أوروبا ({europeCountries.length})</option>
        <option value="americas">الأمريكتين ({americasCountries.length})</option>
        <option value="oceania">أوقيانوسيا ({oceaniaCountries.length})</option>
      </select>

      <div>
        {countries.map((country) => (
          <div key={country.code}>
            {country.nameAr} - {country.cities.length} محافظة
          </div>
        ))}
      </div>
    </div>
  );
}

Express.js API

const express = require('express');
const { getCountryByCode, getCitiesByCountryCode, searchCountries } = require('countries-cities-ar');

const app = express();

// Get all countries
app.get('/api/countries', (req, res) => {
  const { search, lang = 'en' } = req.query;
  
  if (search) {
    const results = searchCountries(search, lang);
    return res.json(results);
  }
  
  res.json(allCountries);
});

// Get country by code
app.get('/api/countries/:code', (req, res) => {
  const country = getCountryByCode(req.params.code);
  if (!country) {
    return res.status(404).json({ error: 'Country not found' });
  }
  res.json(country);
});

// Get cities for a country
app.get('/api/countries/:code/cities', (req, res) => {
  const cities = getCitiesByCountryCode(req.params.code);
  res.json(cities);
});

app.listen(3000, () => {
  console.log('API running on http://localhost:3000');
});

Data Coverage

The library includes carefully curated data for all world regions:

• Africa: 54 countries with major cities
• Asia: 49 countries with major cities
• Europe: 50 countries with major cities
• Americas: 48 countries with major cities
• Oceania: 19 countries with major cities

Total: 250 countries with 4,642 cities/governorates/states/provinces in 3 languages (English, Arabic, French)

Coverage Details

• 🇪🇬 Egypt: 27 governorates with accurate Arabic names
• 🇸🇦 Saudi Arabia: 13 regions (مناطق) with correct Arabic
• 🇦🇪 UAE: 7 emirates with verified names
• 🇮🇶 Iraq: 18 governorates with Arabic translations
• 🇸🇾 Syria: 14 governorates with Arabic names
• 🇯🇴 Jordan: 12 governorates
• 🇱🇧 Lebanon: 8 governorates
• 🇰🇼 Kuwait: 6 governorates
• 🇴🇲 Oman: 11 governorates
• 🇶🇦 Qatar: 8 municipalities
• 🇾🇪 Yemen: 21 governorates
• 🇩🇿 Algeria: 46 wilayas
• 🇹🇳 Tunisia: 24 governorates
• 🇲🇦 Morocco: 87 regions
• 🌍 All Arab countries with complete Arabic translations
• 🗺️ Includes states, provinces, governorates, and regions globally

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test

# Build the library
npm run build

# Lint code
npm run lint

# Format code
npm run format

Contributing

Contributions are welcome! Here's how you can help:

1. Add missing countries or cities: Submit a PR with updates to the data files
2. Fix bugs: Report issues or submit fixes
3. Improve documentation: Help make the docs clearer
4. Add features: Suggest or implement new helper functions

Steps to Contribute

1. Fork the repository
2. Create a new branch: git checkout -b feature/your-feature
3. Make your changes
4. Run tests: npm test
5. Commit your changes: git commit -m 'Add some feature'
6. Push to the branch: git push origin feature/your-feature
7. Submit a pull request

📜 License

MIT © Ziad Mustafa

Free to use for personal and commercial projects.

Support

If you find this library helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📝 Contributing to the documentation

🔧 Troubleshooting

Common Issues

Module not found error in Next.js

Module not found: Can't resolve 'countries-cities-ar'

Solution:

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Next.js cache
rm -rf .next

# Restart dev server
npm run dev

TypeScript errors

If you see type errors, make sure you have the latest version:

npm install countries-cities-ar@latest

Build errors with exports

Make sure you're using version 3.0.1 or later:

npm install countries-cities-ar@^3.0.1

Server/Client component issues in Next.js

Server Components (can use directly):

import { allCountries } from 'countries-cities-ar';

export default function Page() {
  return <div>{allCountries.length}</div>;
}

Client Components (need 'use client'):

'use client';
import { useState } from 'react';
import { allCountries } from 'countries-cities-ar';

export default function Component() {
  const [data] = useState(allCountries);
  return <div>{data.length}</div>;
}

Performance Tips

1. Import only what you need:

// Good
import { getCountryByCode } from 'countries-cities-ar';

// Avoid if you don't need all countries
import { allCountries } from 'countries-cities-ar';

2. Use memoization for filtering:

const filteredCountries = useMemo(() => {
  return allCountries.filter(/* your logic */);
}, [dependencies]);

3. Lazy load data:

import dynamic from 'next/dynamic';

const CountrySelector = dynamic(() => import('./CountrySelector'), {
  loading: () => <p>Loading...</p>,
});

📝 Changelog

3.0.1 (Bug Fix - 2024)

• 🐛 Fixed exports: Corrected package.json exports to match actual build output
• 📦 Fixed imports: import now uses index.js and require uses index.cjs
• ✅ Next.js compatibility: Fixed "Module not found" errors in Next.js
• 📚 Enhanced documentation: Added comprehensive setup guides and troubleshooting

3.0.0 (Major Update - Complete World Coverage)

• 🌍 Complete world data: 250 countries with 4,642 administrative divisions
• 📊 All countries from countries-states-cities-database
• 🇪🇬 All Arab countries with 100% accurate Arabic translations:
  • Egypt: 27 governorates
  • Saudi Arabia: 13 regions
  • UAE: 7 emirates
  • Iraq: 18 governorates
  • Syria: 14 governorates
  • Jordan: 12 governorates
  • Lebanon: 8 governorates
  • Kuwait: 6 governorates
  • Oman: 11 governorates
  • Qatar: 8 municipalities
  • Yemen: 21 governorates
  • Algeria: 46 wilayas
  • Tunisia: 24 governorates
  • Morocco: 87 regions
  • And more...
• 🔤 Trilingual support: English, Arabic, and French
• 📦 TypeScript support with full type definitions
• 🔍 Advanced search functionality
• 📘 Complete documentation with examples
• 🎨 Beautiful demo site with Next.js

1.0.0 (Initial Release)

• ✨ Complete world countries and cities data
• 🔤 Trilingual support: English, Arabic, and French
• 🔍 Advanced search functionality
• 📦 TypeScript support

Made with ❤️ for the Arabic-speaking community