⚠️ DEPRECATED

This package is no longer maintained.

Please use us instead. See: https://www.npmjs.com/package/us

Original README below:

us-states-list

[

A clean, typed, and comprehensive list of all U.S. states and territories with full metadata. The most complete, developer-friendly dataset for U.S. states, DC, and major territories—perfect for forms, civic tech, shipping, and more.

Features

• All 50 states, DC, and major U.S. territories (PR, GU, VI, AS, MP)
• Accurate metadata: name, abbreviation, capital, region, type, FIPS code, land area
• Strong TypeScript types and zero runtime dependencies
• Utility functions for lookups, validation, and region/territory queries
• Dual ESM/CJS support, tree-shakable
• Thoroughly tested with Vitest
• MIT Licensed

Installation

npm install us-states-list

Usage

import {
  usEntries,
  usEntryMapByAbbreviation,
  getEntryByAbbreviation,
  getEntriesByRegion,
  getTerritories,
  isValidAbbreviation,
  getCapitalByAbbreviation,
  getAbbreviationByName,
  USStateEntry,
  USStateAbbreviation,
  USEntryType,
  USRegion,
} from 'us-states-list';

// Get all entries
console.log(usEntries);

// Lookup by abbreviation
const ca = getEntryByAbbreviation('CA');

// Lookup by region
const westStates = getEntriesByRegion('West');

// Get all territories (including DC)
const territories = getTerritories();

// Validate abbreviation
isValidAbbreviation('NY'); // true
isValidAbbreviation('ZZ'); // false

// Get capital by abbreviation
getCapitalByAbbreviation('PR'); // 'San Juan'

// Get abbreviation by name
getAbbreviationByName('California'); // 'CA'

API Reference

Data Exports

• usEntries: Readonly<USStateEntry[]> — All states, DC, and territories
• usEntryMapByAbbreviation: Readonly<Record<USStateAbbreviation, USStateEntry>> — Map by abbreviation

Utility Functions

• getEntryByAbbreviation(abbreviation: string): USStateEntry | undefined
• getEntriesByRegion(region: USRegion | string): USStateEntry[]
• getTerritories(): USStateEntry[]
• isValidAbbreviation(abbreviation: string): boolean
• getCapitalByAbbreviation(abbreviation: string): string | null | undefined
• getAbbreviationByName(name: string): USStateAbbreviation | undefined

Types

• USStateEntry, USStateAbbreviation, USEntryType, USRegion

Data Sources

• USPS Postal Abbreviations
• U.S. Census Bureau Regions & FIPS Codes
• Official Territorial Government Data

License

MIT

Contributing

Pull requests welcome! Please open an issue or PR for improvements, corrections, or new features. See CONTRIBUTING.md if available.