🏛️ @worldkit/states

Fast states, provinces, and territorial subdivisions dataset for JavaScript & TypeScript.

Lookup 4,000+ states, provinces, regions, and territories for any country.

📚 Full Documentation: https://worldkit.in/docs/states

⚡ Features

• 🗺️ 4,000+ Subdivisions: Complete coverage of states, provinces, prefectures, and territories worldwide.
• ⚡ Instant $O(1)$ Filtering: Fast country-based subdivision lookups.
• 📦 Tree-Shakeable ESM: Lightweight footprint (~1.5 KB gzipped).
• 🛡️ Zero External Dependencies: Works out-of-the-box in Browsers, Node.js, Cloudflare Workers, and Edge runtimes.

📦 Install

npm install @worldkit/states
# or
pnpm add @worldkit/states
# or
yarn add @worldkit/states

💡 Usage

import { states, state } from "@worldkit/states";

// 1. Get states/provinces by Country ISO2 Code
const indianStates = states("IN");
console.log(indianStates);
/*
[
  { code: "MH", name: "Maharashtra", country: "IN", type: "state" },
  { code: "DL", name: "Delhi", country: "IN", type: "union territory" },
  ...
]
*/

// 2. Lookup specific state by country and code/name
const california = state("US", "CA");
console.log(california?.name); // "California"

const ontario = state("CA", "Ontario");
console.log(ontario?.code); // "ON"

// 3. Get all states dataset
const allStates = states();

📖 API Reference

states(countryIso2?: string): State[]

Returns array of states/provinces. If countryIso2 is provided (e.g. "CA"), filters by that country.

state(countryIso2: string, stateCodeOrName: string): State | undefined

Look up a specific state by country code and state code (e.g. "CA") or full state name (e.g. "California").

📐 TypeScript Support

Includes strict TypeScript interfaces:

import type { State } from "@worldkit/states";

🔗 Related Packages

Explore the rest of the WorldKit ecosystem:

• @worldkit/core - Unified global data facade.
• @worldkit/countries - 250+ country dataset.
• @worldkit/cities - Major global cities.
• @worldkit/react - React <StateSelect /> component.

📜 License

MIT © WorldKit