df-state-shapes

SVG shapes for US states, DC, and the United States — with a typed lookup API.

Each shape is a 128×128 icon with a single path. Shapes are normalized for UI use (not geographic projections).

Install

npm install df-state-shapes

Quick start

import { getStateShape, dfStateShapes } from 'df-state-shapes';

const california = getStateShape('CA');
// {
//   code: 'CA',
//   slug: 'california',
//   name: 'California',
//   path: 'assets/us/california.svg'
// }

const themed = getStateShape('CA', { variant: 'theme' });
// path → assets/us-theme/california.svg

const all = dfStateShapes.list(); // 52 shapes

API

getStateShape(code, options?)

Returns metadata and a package-relative asset path for a state code.

Option	Default	Values
country	'us'	'us' (more countries planned)
variant	'default'	'default' (fill #030712) or 'theme' (currentColor)

Codes: standard USPS abbreviations (CA, NY, …), plus DC and US (whole-country outline).

listStateShapes(options?)

Returns all shapes for a country. Currently 52 entries: 50 states + DC + US.

dfStateShapes

Namespace object with .get() and .list() — same as the functions above.

resolveStateShapePath(code, options?)

Returns only the asset path string when you don't need full metadata.

Direct SVG imports

Import SVG files directly in bundlers that support it (Vite, Webpack 5+, etc.):

import californiaUrl from 'df-state-shapes/assets/us/california.svg?url';

// With SVGR (React):
import California from 'df-state-shapes/assets/us/california.svg?react';

Theming

Default shapes use a fixed near-black fill (#030712). Themeable variants use currentColor:

import { getStateShape } from 'df-state-shapes';

const { path } = getStateShape('CA', { variant: 'theme' });
// assets/us-theme/california.svg

.state-icon {
  color: #2563eb;
}

Or import directly:

import 'df-state-shapes/assets/us-theme/california.svg';

CDN

Serve assets without npm via jsDelivr:

https://cdn.jsdelivr.net/npm/df-state-shapes@1/assets/us/california.svg
https://cdn.jsdelivr.net/npm/df-state-shapes@1/assets/us-theme/california.svg

Manifest

Non-TypeScript consumers can use the generated manifest:

import manifest from 'df-state-shapes/manifest.json';

Code → slug reference

Code	Slug	Name
AL	alabama	Alabama
AK	alaska	Alaska
AZ	arizona	Arizona
AR	arkansas	Arkansas
CA	california	California
CO	colorado	Colorado
CT	connecticut	Connecticut
DE	delaware	Delaware
DC	district-of-columbia	District of Columbia
FL	florida	Florida
GA	georgia	Georgia
HI	hawaii	Hawaii
ID	idaho	Idaho
IL	illinois	Illinois
IN	indiana	Indiana
IA	iowa	Iowa
KS	kansas	Kansas
KY	kentucky	Kentucky
LA	louisiana	Louisiana
ME	maine	Maine
MD	maryland	Maryland
MA	massachusetts	Massachusetts
MI	michigan	Michigan
MN	minnesota	Minnesota
MS	mississippi	Mississippi
MO	missouri	Missouri
MT	montana	Montana
NE	nebraska	Nebraska
NV	nevada	Nevada
NH	new-hampshire	New Hampshire
NJ	new-jersey	New Jersey
NM	new-mexico	New Mexico
NY	new-york	New York
NC	north-carolina	North Carolina
ND	north-dakota	North Dakota
OH	ohio	Ohio
OK	oklahoma	Oklahoma
OR	oregon	Oregon
PA	pennsylvania	Pennsylvania
RI	rhode-island	Rhode Island
SC	south-carolina	South Carolina
SD	south-dakota	South Dakota
TN	tennessee	Tennessee
TX	texas	Texas
US	united-states	United States
UT	utah	Utah
VT	vermont	Vermont
VA	virginia	Virginia
WA	washington	Washington
WV	west-virginia	West Virginia
WI	wisconsin	Wisconsin
WY	wyoming	Wyoming

Asset layout

assets/
├── us/           # default fills
└── us-theme/     # currentColor fills (generated at build)

Future regions (e.g. Canadian provinces) will follow the same pattern under assets/ca/, using getStateShape('ON', { country: 'ca' }).

Migration from states/

SVGs previously lived at states/california.svg. They now live at assets/us/california.svg. Update any raw GitHub or CDN links accordingly.

Development

npm install
npm run build        # generate theme SVGs, compile TS, write manifest
npm run generate:theme

License

MIT