react-country-kit-core

The high-performance logic and data engine behind react-country-kit. This package provides all the comprehensive datasets, headless hooks, and utilities needed to build custom country-related UI components.

🚀 Features

• 250+ Countries: Full dataset with ISO codes, flags, and phone codes.
• 📑 Localized Metadata: Built-in support for localized Tax ID labels (SSN, VAT, ABN) and Postal Code labels (ZIP, PIN, Postcode).
• 🌍 Global Data: Timezones (with legacy alias support), Currencies, and Native Language names.
• 🏙 Administrative Divisions: State/Province data for all countries.
• 🧠 Headless Hooks: Logic-only hooks (useCountryPicker, usePhoneInput, etc.) for building custom UI with any styling library.
• 📞 Phone Validation: Powered by libphonenumber-js for accurate formatting and validation.

📦 Installation

npm install react-country-kit-core

🛠 Utility Functions

Localized Metadata

Get labels and placeholders for billing/registration forms:

import {
  getTaxLabelByCountry,
  getTaxPlaceholderByCountry,
  getPostalLabelByCountry,
} from "react-country-kit-core";

const label = getTaxLabelByCountry("US"); // "EIN / SSN"
const placeholder = getTaxPlaceholderByCountry("US"); // "00-0000000"
const postalLabel = getPostalLabelByCountry("JP"); // "Postal Code (〒)"

Data Retrieval

import {
  getAllCountries,
  getCountryByIso2,
  searchCountries,
} from "react-country-kit-core";

const usa = getCountryByIso2("US");
const results = searchCountries("united");

🧠 Headless Hooks

Our hooks handle state, filtering, and interaction logic so you can focus on the UI:

import { useCountryPicker } from "react-country-kit-core";

function CustomPicker() {
  const { filteredItems, searchQuery, setSearchQuery, selectItem } =
    useCountryPicker();

  return (
    <div>
      <input
        value={searchQuery}
        onChange={(e) => setSearchQuery(e.target.value)}
      />
      <ul>
        {filteredItems.map((c) => (
          <li key={c.iso2} onClick={() => selectItem(c)}>
            {c.name}
          </li>
        ))}
      </ul>
    </div>
  );
}

📄 Data Structure

export interface Country {
  name: string;
  iso2: string;
  iso3: string;
  phone_code: string;
  division_type: string;
  flag: string;
  flag_url: string;
  currency_code: string;
  language_code: string;
  tax_id_label: string;
  tax_id_placeholder: string;
  postal_code_label: string;
}

📄 License

MIT