🌍 country-select-api

A customizable multilingual country select component for React with emoji flags.

This library provides a simple and elegant country selector with support for internationalized labels, emoji flags, and full customization via React components.

✨ Features

• 🌐 Multi-language country labels
• 🏳️ Emoji flags for countries
• ⚛️ React-based component
• 🎨 Supports full UI customization
• 📦 Lightweight and easy to use

📦 Installation

npm install country-select-api

or with pnpm:

pnpm add country-select-api

🚀 Usage

import { useCountries } from "country-select-api";

const { countryList, findByAlpha2, codeToFlag } = useCountries("en");

console.log(countryList); // All countries with labels in English
console.log(findByAlpha2("US")); // Single country by code
console.log(codeToFlag("US")); // 🇺🇸

import React from "react";
import { CountrySelect } from "country-select-api";

const App = () => {
  return <CountrySelect language="en" callBack={(selectedCountry) => console.log(selectedCountry)} selectedCountryCode="US" />;
};

export default App;

📚 Real-world Example with MUI

import { Autocomplete, TextField } from "@mui/material";
import { useCountries } from "country-select-api";
import { useLanguageStore } from "global/stores/language-store";

export const CountrySelect = () => {
  const { language } = useLanguageStore();
  const { countryList, codeToFlag } = useCountries(language);

  const handleChange = (_: any, value: any) => {
    console.log(value);
  };

  return (
    <Autocomplete
      options={countryList}
      getOptionLabel={(option) => `${codeToFlag(option.code)} ${option.label}`}
      onChange={handleChange}
      renderInput={(params) => <TextField {...params} label="Country" placeholder="Select the country" />}
      sx={{ width: "100%" }}
    />
  );
};

⚙️ Props

| Prop | Type | Required | Description | | --------------------- | --------------------------------------------------- | -------- | ------------------------------------------------------------ | | language | LanguageCode (e.g., "en", "es", etc.) | ✅ | Language code for country labels. | | selectedCountryCode | string | ❌ | Two-letter country code to preselect (e.g., "US"). | | label | string | ❌ | Label for the select field. Default: "Select a country". | | callBack | (value: CountryDataProps) => void | ❌ | Callback when a country is selected. | | customizedSelect | (props: { countryList, language }) => JSX.Element | ❌ | Render your own custom select UI. Overrides the default one. |

🌐 Supported Languages

Supports over 40 languages including:

en, es, fr, de, it, zh, ar, ja, ko, pt, ru, tr, sv, fi, nl, pl, and more.

🧱 Advanced Customization

You can fully replace the default UI using the customizedSelect prop:

<CountrySelect
  language="fr"
  customizedSelect={({ countryList }) => (
    <ul>
      {countryList.map((c) => (
        <li key={c.code}>{c.label}</li>
      ))}
    </ul>
  )}
/>

📁 Folder Structure (Simplified)

src/
├── country-select.tsx       # Main component
├── data/
│   └── world.json           # Country data with translations
├── hooks/
│   └── data-country-hook.tsx
├── types/
│   ├── country-data-props.tsx
│   ├── country-select-props.tsx
│   └── language-code.tsx
├── util/
│   └── code-to-flag.tsx     # Flag emoji utility

🧪 Example of CountryDataProps

{
  id: 840,
  code: "US",
  code2: "USA",
  label: "United States"
}

📜 License

MIT © JhoanVanDam

🛠 Built with

• ⚛️ React 19
• 🧩 TypeScript
• ⚡ Vite
• 📏 ESLint