# GeoIcons: full brief

> GeoIcons is a library of 799 geographic map icons: 255 countries and territories, 167 areas (continents, regions, unions, peninsulas, deserts, basins, seas), and 377 subdivisions (states, provinces, parishes, departments) across 23 countries. Every icon is a map outline of the place, not a flag. It ships as tree-shakable npm packages for React (`@geoicons/react`), Vue (`@geoicons/vue`), Angular (`@geoicons/angular`), and vanilla JavaScript (`@geoicons/vanilla`), and every icon is also a free SVG and PNG download. It is dual-licensed: free under GPLv3 for open source projects, with a commercial license for closed-source use.

## Identity

- Name: GeoIcons
- Website: https://geoicons.io
- Packages: `@geoicons/react`, `@geoicons/vue`, `@geoicons/angular`, `@geoicons/vanilla` on npm. Same icons, names, and props in each; install only the one for your framework.
- GitHub: https://github.com/getgeoicons/geoicons

## What GeoIcons is

GeoIcons draws the outline of places for use in interfaces: country pickers, address and shipping forms, dashboards grouped by region, and data tables. Each icon renders an inline 24×24 SVG with a single stroke style, so countries, regions, and states line up next to each other and next to 24px outline icon sets like Lucide and Heroicons.

Coverage:

- **Countries and territories (255):** keyed by ISO 3166-1 alpha-2 code, plus variants such as `FrMainland`, `AuMainland`, and the UK nations `England`, `Scotland`, `Wales`, and `NorthernIreland`.
- **Areas (167):** continents (`Africa`, `SouthAmerica`), unions and blocs (`EuropeanUnion`, `Eurozone`, `Gcc`, `Ecowas`, `Benelux`), physical regions (`SaharaDesert`, `AmazonBasin`, `Andes`, `Patagonia`), and US regions (`NewEngland`, `MidwestUs`).
- **Subdivisions (377):** all 50 US states plus Washington, D.C., Canada's 13 provinces and territories, Mexico's 32 states, and the parishes, departments, and provinces of 20 Central American and Caribbean countries.

The geometry is simplified so each shape reads clearly at icon sizes (roughly 16 to 64 px). It scales without blurring but is not a substitute for cartographic data in printed or detailed maps.

## Naming

- Countries: the full name or the ISO 3166-1 alpha-2 code in PascalCase. `UnitedStates` and `Us` are the same component; `Japan` and `Jp` are the same component.
- Areas: the area name in PascalCase (`EuropeanUnion`, `SaharaDesert`).
- Subdivisions: the parent country's alpha-2 code plus the region name (`UsTexas`, `CaOntario`, `JmKingston`). They are not keyed by ISO 3166-2, because those codes are numeric for several Caribbean countries.
- Site ids and icon page URLs use the lowercase slug: `/icons/jp`, `/icons/gcc`, `/icons/us-texas`.
- Angular selectors use the same slug: `<geoicon-us>`, `<geoicon-us-texas>`.

## Installation

React (18+):

```bash
npm install @geoicons/react
```

```tsx
import { UnitedStates } from "@geoicons/react/countries";

export default function Example() {
  return <UnitedStates size={48} strokeWidth={1.5} className="text-blue-600" />;
}
```

Vue (3+; on 3.5 and newer, title ids stay stable between server and client rendering):

```bash
npm install @geoicons/vue
```

```vue
<script setup lang="ts">
import { UnitedStates } from "@geoicons/vue/countries";
</script>

<template>
  <UnitedStates :size="48" :stroke-width="1.5" class="text-blue-600" />
</template>
```

Angular (15.1+):

```bash
npm install @geoicons/angular
```

```ts
import { Component } from "@angular/core";
import { UnitedStates } from "@geoicons/angular/countries";

@Component({
  selector: "app-example",
  standalone: true,
  imports: [UnitedStates],
  template: `<geoicon-us [size]="48" [strokeWidth]="1.5" class="text-blue-600" />`,
})
export class ExampleComponent {}
```

Vanilla JS (no framework):

```bash
npm install @geoicons/vanilla
```

```html
<i data-geoicon="us" class="map-icon" aria-label="United States"></i>
```

```js
import { createGeoIcons } from "@geoicons/vanilla";
import { UnitedStates } from "@geoicons/vanilla/countries";

// Replaces every <i data-geoicon="us"> with that icon's <svg>. Style it with CSS:
// .map-icon { width: 48px; height: 48px; color: #2563eb; stroke-width: 1.5 }
createGeoIcons({ us: UnitedStates });
```

## Component API

Every package renders an inline `<svg>` and accepts the same props:

- `size` (number or string, default 24): width and height.
- `strokeWidth` (number, default 1): outline thickness. Use 0 with a fill for a bare silhouette.
- `stroke` (string, default `currentColor`): outline color. A native SVG attribute, so it inherits the text color.
- `fill` (string, default `none`): pass `currentColor` for a solid icon.
- `className`/`class`, `style`, and any other SVG attribute pass through to the `<svg>`. Only `size` and `strokeWidth` are convenience props.
- `aria-label` (string): makes the icon meaningful (`role="img"` plus a `<title>` with a unique id). Without it the icon is decorative (`aria-hidden`).

There is no `variant` or `color` prop. Weight and fill are continuous, controlled by `strokeWidth` and the native `stroke` and `fill` attributes.

Per-framework details:

- React and Vue: extra attributes spread onto the `<svg>`. React icons use no client-only APIs, so they render in React Server Components without `"use client"`.
- Angular: there is no attribute spread. `size`, `strokeWidth`, `stroke`, `fill`, and `aria-label` are explicit inputs; `class`, `style`, and `data-*` attributes go on the `<geoicon-*>` host element.
- Vanilla: `createGeoIcons(map, { attr, root })` scans the DOM for `<i data-geoicon="key">` and replaces each with the icon from your map. `aria-label` and `class` carry over to the `<svg>`. Size, color, stroke width, and fill are set in CSS. Call it again after adding new elements. Each icon is also a factory (`UnitedStates(options)`) that returns an `SVGSVGElement`.

Import subpaths are the same in every package; swap the package name:

- `@geoicons/<framework>/countries`
- `@geoicons/<framework>/areas`
- `@geoicons/<framework>/subdivisions`

## Tree-shaking

Every icon is its own named export in an ES module package with `sideEffects: false`, so bundlers include only the icons you import by name. Each icon adds about 0.3 KB gzipped. For an icon chosen at runtime, import the icons you need into a small object (`{ us: UnitedStates, ca: Canada }`) and look it up by key. GeoIcons deliberately has no `<Icon name="us" />` API, because a string lookup would force every icon into the bundle. In vanilla JS, the map passed to `createGeoIcons` serves the same purpose.

## Downloads

Every icon page (for example https://geoicons.io/icons/jp) has a studio to set stroke weight, fill, and color, then:

- download an SVG that keeps those settings,
- export a PNG at 128, 256, or 512 px,
- copy the import line, the SVG markup, or a Data URI.

An SVG that uses `currentColor` only inherits color when it is inline in HTML. Inside an `<img>` tag it renders black, so pick a color before downloading or use the Data URI as a CSS mask with `background-color`.

## Licensing

Dual-licensed. The icons, packages, and SVG files are identical under both licenses, and icons always render normally.

- **GPLv3 (free):** for projects released as open source under a GPL-compatible license. No key is needed. To hide the one-time console notice, pass the GPL declaration string `GPL-MY-PROJECT-IS-OPEN-SOURCE` to your framework's license provider.
- **Commercial:** a license key, delivered by email, that waives GPLv3 copyleft so you can ship GeoIcons in closed-source products. It is ES256-signed and verified fully offline, with no network call. One-time keys never expire.

License providers (optional, one per framework, all backed by the shared `@geoicons/core` verifier):

- React: `<IconProvider licenseKey="...">` and the `useGeoiconsLicense()` hook.
- Vue: the `GeoiconsLicense` plugin (`app.use(GeoiconsLicense, { licenseKey })`) and the `useGeoiconsLicense()` composable.
- Angular: `provideGeoiconsLicense(key)` and `GeoiconsLicenseService`.
- Vanilla: `initGeoiconsLicense(key)`.

Enforcement is legal, not technical. A project without a confirmed license sees a single console notice per session. There is no watermark, no lock, and no feature gate.

Pricing:

- Free (GPLv3): $0, for open source projects.
- Hobby: $99 one-time or $29/year. One product, for freelancers and indie developers.
- Business: $199 one-time or $59/year. Unlimited products, for teams and agencies.
- Extended: $399 one-time or $129/year. Redistribution rights for SDKs, themes, and builders that pass the icons to end users.
- Every paid tier includes use in closed-source and commercial apps, the Figma source file and raw SVG bundle, and updates as the catalog grows.

## FAQ

Q: Is GeoIcons free?
A: Yes, when your project is released as open source under a GPL-compatible license. If you ship GeoIcons in a closed-source product, you need a commercial license.

Q: Are GeoIcons flags?
A: No. Every icon is a map outline of the place's borders, drawn as a 24×24 SVG. They are an alternative to flag icons and flag emojis in country selectors.

Q: Which frameworks are supported?
A: React, Vue, Angular, and vanilla JavaScript, with one npm package each and the same icons, names, and props.

Q: Does GeoIcons include US states and other subdivisions?
A: Yes. 377 subdivisions across 23 countries, including all 50 US states plus Washington, D.C., Canada's provinces and territories, and Mexico's states. Import them from the `/subdivisions` subpath, for example `UsTexas`.

Q: Can I use the icons without npm?
A: Yes. Every icon page offers an SVG download, PNG exports at 128, 256, and 512 px, and a copyable Data URI.

Q: Does the license key expire?
A: One-time keys never expire. The annual option is a lower-cost way to pay that keeps updates current.

Q: How is the license enforced?
A: Legally, not technically. The optional license provider verifies the key fully offline and hides the one-time console notice when the project is licensed.

## Key URLs

- Home: https://geoicons.io
- Catalog: https://geoicons.io/icons (countries: /icons/countries, areas: /icons/areas, subdivisions: /icons/subdivisions)
- Icon pages: https://geoicons.io/icons/{slug} (for example /icons/jp, /icons/gcc, /icons/us-texas)
- Docs: https://geoicons.io/docs (getting started, icon types, API, styling, accessibility, licensing, changelog)
- API docs: https://geoicons.io/docs/api (React, Vue, Angular, vanilla JS)
- Licensing docs: https://geoicons.io/docs/commercial-license
- Use cases: https://geoicons.io/use-cases/react-map-icons, https://geoicons.io/use-cases/svg-map-icons, https://geoicons.io/use-cases/open-source-map-icons
- Blog: https://geoicons.io/blog (RSS: /blog/feed.xml)
- Pricing: https://geoicons.io/pricing
- npm: https://www.npmjs.com/package/@geoicons/react (also /vue, /angular, /vanilla)
- GitHub: https://github.com/getgeoicons/geoicons