Detalhes do pacote

us-states-list

zenluv19MIT1.0.2

[DEPRECATED] A clean, typed, and comprehensive list of all U.S. states and territories with full metadata.

us states, united states, state list, territories

readme (leia-me)

⚠️ DEPRECATED

This package is no longer maintained.

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

Original README below:

us-states-list

NPM version License: MIT

[Types

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

License

MIT

Contributing

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