Locale

Overview

Locale is a high-performance, tree-shakeable utility library providing standardized international country metadata, phone dialing codes, and lightweight CSS-driven SVG flags for web applications.

It is designed to power international phone inputs, registration forms, billing address selectors, and localization layers with strict TypeScript typings.

Core Capabilities

• Normalized Country Metadata: 240+ international countries and territories with official common names, ISO-2 alpha codes, and international dialing codes.
• Fast In-Memory Lookup APIs: Instant case-insensitive resolution by ISO-2 code or telephone dial code.
• Optimized CSS Flag Icons: CSS-based SVG flags (@nofinite/locale/flags.css) that avoid embedding hundreds of heavy raster images or separate HTTP requests into your client bundles.
• Strict TypeScript Types: Fully typed Country interface with zero any leakage.
• Framework Agnostic: Works seamlessly in Next.js, Vite, Node.js, and pure JavaScript runtimes.

Quick Example

import { getCountryByCode, getCountryByDialCode, countries } from '@nofinite/locale';

// 1. Lookup country by ISO-2 code (case-insensitive)
const usa = getCountryByCode('US');
console.log(usa);
// { name: 'United States', iso2: 'US', dialCode: '+1' }

// 2. Lookup country by telephone dial code
const india = getCountryByDialCode('+91');
console.log(india);
// { name: 'India', iso2: 'IN', dialCode: '+91' }

// 3. Iterate over the complete country catalog for a select dropdown
const options = countries.map(c => ({
  value: c.iso2,
  label: `${c.name} (${c.dialCode})`
}));

Rendering Flags with CSS

Import the flag icons stylesheet in your app:

import '@nofinite/locale/flags.css';

export function FlagBadge({ iso2 }: { iso2: string }) {
  return (
    <span className="inline-flex items-center gap-2">
      <span className={`nui-flag nui-flag-${iso2.toLowerCase()}`} />
      <span>{iso2}</span>
    </span>
  );
}

API Summary

Next Steps

• Follow the Installation Guide to install and configure the package.
• Explore Country Lookup for country filtering and search recipes.
• Explore SVG Flags for flag sizing, styling, and form integration.