DOCSEARCHbyAlgolia
Submit Docs

GeoIcons

website·Indexed 30 days ago

https://geoicons.io/docs

A library of 799 geographic map icons, including 255 countries and territories and 167 areas such as continents, regions, and unions, designed for use in country selectors.

Tokens
1.4K
Snippets
5
Records
13
Agent score
17%

What's inside GeoIcons

  1. Overview of GeoIcons library

    GeoIcons is a library of 799 geographic map outline icons (not flags) designed for UI elements like country pickers and dashboards. It provides 255 countries/territories, 167 areas (continents, regions, unions), and 377 subdivisions. Icons are rendered as 24x24 SVGs with a single stroke style, making them compatible with icon sets like Lucide and Heroicons. The geometry is simplified for clarity at sizes between 16px and 64px.

  3. Install and use GeoIcons in Angular

    GeoIcons for Angular (15.1+) uses custom selectors based on the icon slug (e.g., <geoicon-us>). Icons are imported from the /countries, /areas, or /subdivisions subpaths.
    npm install @geoicons/angular
    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 {}

  4. Install and use GeoIcons in React

    GeoIcons for React (18+) supports React Server Components without requiring the "use client" directive. Icons are imported from the /countries, /areas, or /subdivisions subpaths.
    npm install @geoicons/react
    import { UnitedStates } from "@geoicons/react/countries";

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

  5. Install and use GeoIcons in Vue

    GeoIcons for Vue (3+) ensures stable title IDs between server and client rendering on version 3.5 and newer. Icons are imported from the /countries, /areas, or /subdivisions subpaths.
    npm install @geoicons/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>

  6. Optimize GeoIcons bundle size with tree-shaking

    GeoIcons is designed for tree-shaking (sideEffects: false). To keep bundle sizes small, import icons by name. Avoid creating a generic <Icon name="us" /> component that imports the entire library. If icons must be chosen at runtime, create a small lookup object containing only the required icons.
    // Correct way to handle runtime selection
import { UnitedStates, Canada } from "@geoicons/react/countries";
const iconMap = { us: UnitedStates, ca: Canada };
const SelectedIcon = iconMap[runtimeKey];

  7. Install and use GeoIcons with Vanilla JavaScript

    For Vanilla JS, you can use the createGeoIcons function to scan the DOM for elements with the data-geoicon attribute and replace them with the corresponding SVG. Alternatively, icons can be used as factories that return an SVGSVGElement.
    npm install @geoicons/vanilla
    <i data-geoicon="us" class="map-icon" aria-label="United States"></i>
    import { createGeoIcons } from "@geoicons/vanilla";
import { UnitedStates } from "@geoicons/vanilla/countries";

// Replaces every <i data-geoicon="us"> with the SVG
createGeoIcons({ us: UnitedStates });

  8. Download GeoIcons as static assets

    If you are not using npm, you can obtain icons directly from the individual icon pages on the GeoIcons website. Available formats include: SVG downloads, PNG exports (128px, 256px, and 512px), and copyable Data URIs.

  9. Use geographic subdivisions in GeoIcons

    GeoIcons includes 377 subdivisions across 23 countries, including all 50 US states (plus Washington, D.C.), Canadian provinces and territories, and Mexican states. These icons must be imported from the /subdivisions subpath. For example, to use the Texas icon, import UsTexas from the subdivisions path.

  10. Manage GeoIcons licensing and commercial use

    GeoIcons is dual-licensed:

    • GPLv3 (Free): For open-source projects. To remove the one-time console notice, provide the string GPL-MY-PROJECT-IS-OPEN-SOURCE to the license provider.
    • Commercial: Required for closed-source products. Provides an ES256-signed key for offline verification.

    License Provider Setup:

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

  11. Identify GeoIcons by name and slug

    GeoIcons uses specific naming conventions for imports and selectors:

    • Countries: Full name or ISO 3166-1 alpha-2 code in PascalCase (e.g., UnitedStates or Us).
    • Areas: Area name in PascalCase (e.g., EuropeanUnion, SaharaDesert).
    • Subdivisions: Parent country alpha-2 code + region name in PascalCase (e.g., UsTexas, CaOntario).
    • Slugs: Lowercase versions used in URLs and Angular selectors (e.g., us, us-texas).

  12. GeoIcons licensing and enforcement

    GeoIcons licenses are enforced legally rather than technically. One-time license keys do not expire. The license provider verifies keys offline; once a project is licensed, the optional license provider hides the one-time console notice.