svg-world-maps

v0.5.0

Published

12 days ago

World map SVG for any JavaScript framework

svg-world-maps

Simple, lightweight SVG maps for JavaScript projects.

🎉 Now with 8 Country Maps! Hover Effects & Click Support!

📚 Documentation: Wiki Home • Getting Started • Optional Maps
💬 Community: Discussions • Report Issue

Features

🌍 Multiple Maps: World map + 8 country maps (USA, Germany, India, Iran, Netherlands, France, Australia, Brazil, Great Britain, and more coming)
📏 Flexible Sizing: 8 preset sizes + custom scale factors
🎨 Customizable: Background, borders, and hover colors
👆 Interactive: Click support via data-code and data-name attributes
⚡ Zero dependencies: Pure SVG output
🛠 Framework agnostic: Works with React, Vue, Svelte, Vanilla JS, etc.
📦 TypeScript support: Full type definitions included
🔧 Simple API: One function to rule them all

Installation

npm install [email protected]

💡 Optional Maps: Keep your bundle small by only adding the maps you need.

npx add-map usa          # Add USA map
npx add-map germany      # Add Germany map
npx add-map india        # Add India map
npx add-map iran         # Add Iran map
npx add-map netherlands  # Add Netherlands map
npx add-map france       # Add France map
npx add-map australia    # Add Australia map
npx add-map brazil       # Add Brazil map
npx add-map gb           # Add Great Britain map

Learn more →

Usage

React + Vite

import { createMap } from "svg-world-maps";

const App = () => {
  // Create a world map with custom options
  const worldMap = createMap("world", {
    background: "#e6f3ff",   // Background color
    borders: "#2c3e50",      // Border color
    hoverColor: "rgba(59, 130, 246, 0.3)", // Hover highlight
    size: "lg"               // Size preset
  });

  return (
    <div dangerouslySetInnerHTML={{ __html: worldMap }} />
  );
};

export default App;

Vanilla JavaScript with Click Handling

import { createMap } from "svg-world-maps";

const mapSVG = createMap("world", {
  background: "#e6f3ff",
  borders: "#2c3e50",
  hoverColor: "lightblue"
});

const container = document.getElementById("map-container");
container.innerHTML = mapSVG;

// Handle region clicks using data attributes
container.addEventListener("click", (e) => {
  const target = e.target;
  const code = target.dataset.code;
  const name = target.dataset.name;
  
  if (code && name) {
    console.log(`Clicked: ${name} (${code})`);
    // Show tooltip, navigate, filter data, etc.
  }
});

API Reference

`createMap(mapType, options)`

Creates an SVG map string.

Parameters

| Parameter | Type | Description | Options | |-----------|------|-------------|---------| | mapType | string | Type of map to generate | "world", "usa", "germany", "india", "iran", "netherlands", "france", "australia", "brazil", "gb" | | options | object | Configuration options | See below |

* Optional maps require setup via npx add-map — see guide

Options

| Option | Type | Description | Default | |--------|------|-------------|---------| | background | string | Map background color (any valid CSS color) | "currentColor" | | borders | string | Country/state border color | "#000000" | | hoverColor | string | Color applied to regions on hover | undefined | | size | string \| number | Map size (preset or custom scale) | "lg" |

Note on hoverColor: The library outputs the color value in the SVG. Actual hover behavior requires CSS :hover rules or JavaScript event listeners in your implementation.

Size Options

Preset Sizes

| Preset | Scale | Description | |--------|-------|-------------| | "xs" | 0.25x | Extra small - 25% of original | | "sm" | 0.5x | Small - 50% of original | | "md" | 0.75x | Medium - 75% of original | | "lg" | 1x | Large - 100% of original (default) | | "xl" | 1.5x | Extra large - 150% of original | | "2xl" | 2x | 2X Large - 200% of original | | "3xl" | 2.5x | 3X Large - 250% of original | | "4xl" | 3x | 4X Large - 300% of original |

Custom Scale Factors

Use any number for precise control:

{ size: 0.33 }  // Exactly one-third size
{ size: 1.25 }  // 25% larger
{ size: 1.75 }  // 75% larger
{ size: 2.5 }   // Two and a half times larger
{ size: 0.8 }   // 20% smaller

Interactive Features

Click Handling with Data Attributes

Every region in the generated SVG includes two data attributes:

| Attribute | Description | Example | |-----------|-------------|---------| | data-code | Short region identifier | "US-CA", "IN-MH", "DE-BY", "GB-ENG" | | data-name | Full region name | "California", "Maharashtra", "Bavaria", "England" |

React Example with Toast Notification:

import { useEffect, useRef, useState } from "react";
import { createMap, registerMapData } from "svg-world-maps";
import usaData from "./maps/usa";

registerMapData("usa", usaData);

const App = () => {
  const [selected, setSelected] = useState(null);
  const containerRef = useRef(null);

  const Map = createMap("usa", {
    background: "#e6f3ff",
    borders: "#2c3e50",
    size: "md",
    hoverColor: "purple"
  });

  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const handleClick = (e) => {
      const target = e.target;
      const code = target.dataset.code;
      const name = target.dataset.name;

      if (code && name) {
        setSelected({ name, code });
        setTimeout(() => setSelected(null), 3000);
      }
    };

    container.addEventListener("click", handleClick);
    return () => container.removeEventListener("click", handleClick);
  }, []);

  return (
    <div>
      <div ref={containerRef} dangerouslySetInnerHTML={{ __html: Map }} />
      {selected && (
        <div className="toast">
          {selected.name} ({selected.code})
        </div>
      )}
    </div>
  );
};

Use Cases:

Show region details in a tooltip or modal
Navigate to a detail page: /regions/${code}
Filter dashboard data by selected region
Track analytics per region click

Examples

Basic Examples

// World map with default settings
createMap("world");

// USA map with hover effect (requires optional setup)
createMap("usa", {
  background: "#f0f4f8",
  borders: "#334155",
  hoverColor: "rgba(59, 130, 246, 0.3)"
});

// Germany map - extra small
createMap("germany", { size: "xs" });

// India map with custom colors
createMap("india", {
  background: "#fff5e6",
  borders: "#ff9933",
  hoverColor: "rgba(255, 153, 51, 0.3)"
});

// Iran map - medium size
createMap("iran", { size: "md" });

// World map - custom scale with borders
createMap("world", {
  borders: "#3498db",
  size: 1.25
});

React: Multiple Maps

import { createMap } from "svg-world-maps";

const Maps = () => {
  const world = createMap("world", { size: "sm", hoverColor: "lightgray" });
  const germany = createMap("germany", { size: "md", hoverColor: "lightblue" });
  const india = createMap("india", { size: "md", hoverColor: "lightgreen" });

  return (
    <div>
      <h3>World Map</h3>
      <div dangerouslySetInnerHTML={{ __html: world }} />
      
      <h3>Germany Map</h3>
      <div dangerouslySetInnerHTML={{ __html: germany }} />
      
      <h3>India Map</h3>
      <div dangerouslySetInnerHTML={{ __html: india }} />
    </div>
  );
};

Available Maps

| Map | Type | Description | Since | Status | |-----|------|-------------|-------|--------| | "world" | 🌍 | Complete world map with all 195 countries | v0.2.0 | ✅ Included by default | | "afghanistan" | 🗺️ | Afghanistan map with 34 provinces | v0.1.0 | 🔁 Optional | | "usa" | 🇺🇸 | USA map with all 50 states + DC | v0.4.0 | 🔁 Optional | | "germany" | 🇩🇪 | Germany map with 16 states | v0.5.0 | 🔁 Optional | | "india" | 🇮🇳 | India map with 28 states + 8 union territories | v0.5.0 | 🔁 Optional | | "iran" | 🇮🇷 | Iran map with 31 provinces | v0.5.0 | 🔁 Optional | | "netherlands" | 🇳🇱 | Netherlands map with 12 provinces | v0.5.0 | 🔁 Optional | | "france" | 🇫🇷 | France map with 18 regions | v0.5.0 | 🔁 Optional | | "australia" | 🇦🇺 | Australia map with 6 states + 10 territories | v0.5.0 | 🔁 Optional | | "brazil" | 🇧🇷 | Brazil map with 26 states + federal district | v0.5.0 | 🔁 Optional | | "gb" | 🇬🇧 | Great Britain map with constituent countries | v0.5.0 | 🔁 Optional |

🔁 Optional maps keep your bundle small. Add them only when needed:
npx add-map usa
npx add-map germany
npx add-map india
npx add-map iran
npx add-map netherlands
npx add-map france
npx add-map australia
npx add-map brazil
npx add-map gb
Full setup guide →

Roadmap

[x] Afghanistan map (v0.1.0)
[x] World map (v0.2.0)
[x] Optional maps system (v0.3.0)
[x] USA map + hoverColor + click support via data attributes (v0.4.0)
[x] Germany, India, Iran, Netherlands, France, Australia, Brazil, Great Britain maps (v0.5.0)
[ ] More country maps (Canada, China, Japan, Mexico, etc.)
[ ] Keyboard navigation & accessibility improvements
[ ] Export to PNG/SVG file

Migration Guide

From v0.4.0 to v0.5.0

No breaking changes. New maps are optional additions.

To use new country maps:

# Add any of the new maps
npx add-map germany
npx add-map india
npx add-map iran
# ... and more

# Register in your code
import { registerMapData } from "svg-world-maps";
import germanyData from "./src/maps/germany";
registerMapData("germany", germanyData);

From v0.1.0 to v0.2.0

// v0.1.0 (old)
import { createAfghanistanMap } from "svg-world-maps";
const map = createAfghanistanMap({ 
  fill: "#ff0000", 
  stroke: "#ffffff" 
});

// v0.2.0 (new)
import { createMap } from "svg-world-maps";
const map = createMap("afghanistan", { 
  background: "#ff0000", 
  borders: "#ffffff",
  size: "lg" 
});

From v0.3.x to v0.4.0

No breaking changes. New features are optional.

To use the USA map:

# 1. Add the optional map
npx add-map usa

# 2. Register it in your code
import { registerMapData } from "svg-world-maps";
import usaData from "./src/maps/usa";
registerMapData("usa", usaData);

To use hoverColor or click handling:

// Add hover effect
createMap("world", { hoverColor: "rgba(0, 123, 255, 0.4)" });

// Add click handling (vanilla JS)
container.addEventListener("click", (e) => {
  if (e.target.dataset.code) {
    console.log(e.target.dataset.name);
  }
});

📚 Documentation & Support

| Resource | Link | |----------|------| | 🏠 Wiki Home | github.com/homayounmmdy/svg-world-maps/wiki | | 🚀 Getting Started | Quick start guide | | 🗺️ Optional Maps | Add USA, Afghanistan & more | | 💬 Discussions | Ask questions & share ideas | | 🐛 Report Issue | Open a bug report |

Contributing

Contributions are welcome! Feel free to:

🐛 Report bugs
💡 Suggest new features
🌍 Add new country maps
📝 Improve documentation

License

Support

If you find this package helpful, please consider:

⭐ Starring on GitHub
🐦 Sharing on Twitter
📢 Telling your friends

Made with ❤️ for the open-source community

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

svg-world-maps

Features

Installation

Usage

React + Vite

Vanilla JavaScript with Click Handling

API Reference

createMap(mapType, options)

Parameters

Options

Size Options

Preset Sizes

Custom Scale Factors

Interactive Features

Click Handling with Data Attributes

Examples

Basic Examples

React: Multiple Maps

Available Maps

Roadmap

Migration Guide

From v0.4.0 to v0.5.0

From v0.1.0 to v0.2.0

From v0.3.x to v0.4.0

📚 Documentation & Support

Contributing

License

Support

`createMap(mapType, options)`