svg-world-maps

Simple, lightweight, and highly customizable SVG maps for modern JavaScript projects.

📚 Full Documentation: svg-world-maps.vercel.app
💬 Community: Discussions • Issues

🎉 Welcome to v1.0.1!

We are thrilled to announce the v1.0.1 stable release! This major milestone brings:

• 🌍 212+ Maps: World map + 211 country and region maps (USA, China, Japan, Germany, Iran, Brazil, and many more!).
• ⚡ Zero Dependencies: Pure, lightweight SVG output.
• 🛠 Framework Agnostic: Works flawlessly with React, Next.js, Vue, Svelte, Angular, or Vanilla JS.
• 📦 Tree-shakeable: Keep your bundle tiny by only adding the specific maps you need.
• 🖱️ Interactive: Built-in hover effects, native tooltips, static labels, and click handling via data attributes.
• 🛡️ TypeScript Ready: Full, strict type definitions included out of the box.

🚀 Installation

npm install svg-world-maps
# or
yarn add svg-world-maps
# or
pnpm add svg-world-maps

⚡ Quick Start

React / Next.js

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

const App = () => {
  // Generate the SVG string
  const worldMap = createMap("world", {
    background: "#e6f3ff",
    borders: "#2c3e50",
    hoverColor: "rgba(59, 130, 246, 0.3)",
    showTooltip: true,  // Native hover tooltips
    showLabels: true,   // Static text labels (where supported)
    size: "lg"          // Responsive size preset
  });

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

export default App;

Vanilla JavaScript

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

const mapSVG = createMap("world", {
  background: "#f8fafc",
  borders: "#94a3b8",
  hoverColor: "#3b82f6",
  showTooltip: true
});

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

// Easy click handling via data attributes
container.addEventListener("click", (e) => {
  if (e.target.tagName === "path") {
    const code = e.target.dataset.code; // e.g., "US-CA"
    const name = e.target.dataset.name; // e.g., "California"
    console.log(`Clicked: ${name} (${code})`);
  }
});

🗺️ Adding Optional Maps

To keep your production bundle size minimal, only the world map is included by default. Add any of the 211+ optional maps on-demand using our CLI:

# Add a specific map (e.g., usa, germany, japan, brazil)
npx add-map usa

# Automatically register it in your codebase (DX booster!)
npx register-map

👉 See the full list of 212+ available maps in the Documentation

📚 Learn More

The README is just the beginning. For comprehensive guides, API references, and advanced use cases, visit our official documentation:

| Resource | Link | | :--- | :--- | | 🚀 Getting Started | Installation & Basic Usage | | ⚙️ API Reference | createMap, registerMapData & Options | | 📏 Size & Scaling | Presets and custom scale factors | | 🖱️ Interactivity | Tooltips, Labels, and Click Handling | | 📊 Maps Info Report | Real-time status of all 212+ maps | | 🔄 Migration Guide | Upgrading to v1.0.0 |

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. We welcome:

• 🐛 Bug reports and fixes
• 💡 Feature requests
• 🌍 New country/region map additions
• 📝 Documentation improvements

Please read our Code of Conduct before contributing.

📜 License

This project's code is distributed under the MIT License. See LICENSE for more information.

🗺️ Map Data Attribution

Please note that the underlying SVG map data (paths, viewBox coordinates, and labels) for specific countries and regions included in this package is sourced from SimpleMaps.

This map data is used in accordance with the SimpleMaps SVG Map Library License. The map data itself is not covered by the MIT license of this project and remains subject to SimpleMaps' terms of use (free for commercial use, attribution appreciated, and no redistribution "as is" without added value).

If you use these maps in your own projects, we kindly ask that you acknowledge SimpleMaps.

❤️ Support

If you find svg-world-maps helpful in your project, please consider:

• ⭐ Starring the repository on GitHub
• 🐦 Sharing it with your network
• 📢 Telling your friends and colleagues

Made with ❤️ for the open-source community by homayounmmdy