Subdivision icons: states, provinces, and parishes as SVGs

GeoIcons started with countries: the outline of Japan, the shape of Brazil, one named export each. The question that kept coming back was the next level down. You are building a US sales dashboard, or a map of Canadian provinces, or a Caribbean travel app, and a country icon is too coarse. You need Texas, not the United States.

Subdivisions are that level. The library now ships 377 of them: the internal shapes of a country, drawn in the same outline style as the rest of the set and imported the same way.

import { UsTexas } from '@geoicons/react/subdivisions';

export default function App() {
  return <UsTexas size={40} aria-label="Texas" />;
}

What ships today

The first batch covers 23 countries, chosen so the most-requested maps are complete rather than scattered:

• United States: 51 icons, all 50 states plus the District of Columbia.
• Mexico: 32 states.
• Canada: 13 provinces and territories.
• Central America and the Caribbean: 20 more countries, from Guatemala, Honduras, and Nicaragua to Jamaica, the Bahamas, and Trinidad and Tobago. These carry the local unit, so you get parishes, departments, and districts rather than a forced "state" label.

That is 377 icons in total. Each one is a flat outline of the subdivision's real border, at the same weight and viewBox as the country and area icons, so a state sits next to its country without looking like it came from a different set.

A subdivision icon is the outline of the region's border, the same way a GeoIcons country is the outline of a country. It carries the shape and nothing else: no seal, no coat of arms, no text label.

How they are named

This is the part worth reading before you install. Country icons use ISO 3166 alpha-2 in PascalCase, so the US is Us and France is Fr. Subdivisions extend that: the parent country's alpha-2 code, then the subdivision name in PascalCase.

import { UsTexas } from '@geoicons/react/subdivisions';    // Texas, US
import { CaQuebec } from '@geoicons/react/subdivisions';   // Quebec, Canada
import { MxYucatan } from '@geoicons/react/subdivisions';  // Yucatan, Mexico
import { JmKingston } from '@geoicons/react/subdivisions';  // Kingston, Jamaica

You might expect the ISO 3166-2 code, US-TX becoming something like UsTx. It does not, for a concrete reason. ISO 3166-2 is numeric for eleven Caribbean countries: Jamaica's Kingston parish is JM-01, not JM-KIN. Naming an export Jm01 would ship a component nobody can read or guess. So the id is built from the human name instead. Kingston is JmKingston, and the numeric JM-01 is kept as a search alias rather than baked into the component name.

That trade means the export name reads cleanly and stays consistent across all 23 countries, whether the local ISO code is alphabetic or numeric. When you know a subdivision by its ISO code, the catalog search still finds it, so US-TX and JM-01 both resolve to the right icon.

How to use them

Install the framework package if you have not already, then import a subdivision by name:

npm i @geoicons/react

import { UsCalifornia, UsTexas, UsNewYork } from '@geoicons/react/subdivisions';

export default function StateRow() {
  return (
    <div className="flex items-center gap-3">
      <UsCalifornia size={28} aria-label="California" />
      <UsTexas size={28} aria-label="Texas" />
      <UsNewYork size={28} aria-label="New York" />
    </div>
  );
}

Subdivisions take the same props as every other GeoIcons component. Size them with size, color them through currentColor, and adjust the outline weight with strokeWidth:

// 32px, inherits the surrounding text color
<UsTexas size={32} />

// thicker outline, explicit color
<UsTexas size={32} strokeWidth={2} style={{ color: '#2563eb' }} />

// labeled for assistive tech
<UsTexas size={32} aria-label="Texas" />

Add aria-label when the icon carries meaning on its own. Leave it off, or pass aria-hidden, when a text label already names the region next to it. Each icon namespaces its own <title> internally, so you can render fifty states on one page without id collisions.

The other frameworks

The subdivision export path is identical everywhere. Vue and Vanilla use the same PascalCase names:

// Vue
import { UsTexas } from '@geoicons/vue/subdivisions';

// Vanilla
import { UsTexas } from '@geoicons/vanilla/subdivisions';

Angular follows its element convention, so UsTexas is the <geoicon-us-texas> host element:

<geoicon-us-texas [size]="32" aria-label="Texas"></geoicon-us-texas>

Choosing a subdivision at runtime

When the region is only known at render time, from an API response or a route param, do not reach for a lookup that pulls the whole set. Import the subdivisions you support and put them in a small map:

import { UsCalifornia, UsTexas, UsNewYork } from '@geoicons/react/subdivisions';

const STATES = {
  ca: UsCalifornia,
  tx: UsTexas,
  ny: UsNewYork,
} as const;

export function StateIcon({ code }: { code: keyof typeof STATES }) {
  const Icon = STATES[code];
  return <Icon size={28} aria-label={code.toUpperCase()} />;
}

The map lists only the icons you imported, so the bundler still drops the 374 subdivisions you never touch. There is no central registry and no <Icon name="us-texas" /> API, on purpose: those defeat tree-shaking, and the whole point of one-export-per-icon is that a large library costs you only what you render.

What is coming next

23 countries is the start, not the shape of the finished set. The rest of the world's subdivisions are in progress: European regions, Asian provinces, and the remaining South American and African administrative units are being drawn to the same outline standard and will land in future releases. The naming rule stays fixed, so anything you learn about UsTexas today applies to FrBretagne or JpHokkaido when they arrive.

If a subdivision you need is not in this batch yet, the country and area sets already cover the level above it, and the subdivision for that country is likely on the near roadmap.

FAQ

How many subdivision icons are there?

377 subdivision icons across 23 countries in the first release: all 50 US states plus DC, 32 Mexican states, 13 Canadian provinces and territories, and the subdivisions of 20 Central American and Caribbean countries. More regions are in progress for future releases.

How are subdivision icons named?

By the parent country's ISO 3166 alpha-2 code followed by the subdivision name in PascalCase, for example UsTexas, CaOntario, and MxJalisco. The name is used instead of the ISO 3166-2 code because that code is numeric for eleven Caribbean countries, which would produce unreadable exports like Jm01. The ISO code is kept as a search alias.

How do I import a subdivision icon in React?

Install @geoicons/react and import from the subdivisions entry: import { UsTexas } from '@geoicons/react/subdivisions'. It renders as a <UsTexas /> component you size and color like any other GeoIcon. Vue, Vanilla, and Angular expose the same names from their own subdivisions entry.

Are subdivision icons tree-shakable?

Yes. Each subdivision is its own named export, so a bundler includes only the ones you import and drops the rest. Importing three states adds three modules to your bundle, not all 377.

Get started

Install the package and render your first subdivision:

npm i @geoicons/react

import { UsTexas } from '@geoicons/react/subdivisions';

export default function App() {
  return <UsTexas aria-label="Texas" />;
}

Browse the subdivision catalog to see the full set, or read the prop and import reference. New to the library? Start with the launch post.