ng-simple-maps

January 18, 2026 · View on GitHub

Beautiful, lightweight SVG world maps for Angular applications. Create stunning interactive choropleth maps, data visualizations, geographic dashboards, and analytics with D3 geo projections. Perfect for business intelligence, travel apps, educational tools, and corporate websites.

🚀 Live Demo & Documentation

View Interactive Demo →

Angular Version Support

This library supports Angular 15+.

Peer Dependencies: @angular/core@>=15.0.0 and @angular/common@>=15.0.0

🗺️ World Map Library | 📊 Data Visualization | 🌍 Geographic Mapping | 📱 Responsive Design | ⚡ Interactive Maps

Features

One Simple Component - Everything you need in <asm-map>
Data-Driven - Pass arrays of markers, annotations, and lines
Lines/Connections - Draw curved flight paths between points
Choropleth Maps - Color countries by data values
Country Labels - Show country names with zoom-based visibility
Zoom to Feature - Click countries to zoom and center on them
Graticule Grid - Latitude/longitude grid lines
Zoom & Pan - Enable with a single property
Tooltips - Automatic on hover, fully customizable
15+ Projections - Mercator, Equal Earth, Orthographic, and more
Continent Filtering - Show only the regions you need
Multiple Marker Shapes - Circle, diamond, pin, star
Fully Responsive - Scales to any screen size
TypeScript - Full type safety

Installation

npm install ng-simple-maps

Quick Start

import { Component } from '@angular/core';
import { MapComponent } from 'ng-simple-maps';

@Component({
  imports: [MapComponent],
  template: `
    <asm-map
      [geography]="worldData"
      [zoomable]="true"
      [showTooltip]="true">
    </asm-map>
  `
})
export class MyComponent {
  worldData = 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json';
}

That's it! You have a fully interactive world map with zoom, pan, and tooltips.

Examples

With Markers

import { MapComponent, MapMarker } from 'ng-simple-maps';

@Component({
  imports: [MapComponent],
  template: `
    <asm-map
      [geography]="worldData"
      [markers]="markers"
      [zoomable]="true"
      [showTooltip]="true"
      (markerClick)="onMarkerClick($event)">
    </asm-map>
  `
})
export class MyComponent {
  worldData = 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json';

  markers: MapMarker[] = [
    { coordinates: [-74.006, 40.7128], label: 'New York', color: '#FF5533' },
    { coordinates: [2.3522, 48.8566], label: 'Paris', color: '#FFD700', size: 8 },
    { coordinates: [37.6173, 55.7558], label: 'Moscow', shape: 'diamond' }
  ];

  onMarkerClick(event) {
    console.log('Clicked:', event.marker.label);
  }
}

With Annotations

markers: MapMarker[] = [
  { coordinates: [-74.006, 40.7128], label: 'New York' }
];

annotations: MapAnnotation[] = [
  { coordinates: [-74.006, 40.7128], text: 'New York', dx: 50, dy: -30, curve: 0.5 }
];

<asm-map
  [geography]="worldData"
  [markers]="markers"
  [annotations]="annotations">
</asm-map>

Continent Filtering

<!-- Single continent -->
<asm-map [geography]="worldData" continents="Europe"></asm-map>

<!-- Multiple continents -->
<asm-map [geography]="worldData" [continents]="['Asia', 'Europe']"></asm-map>

Custom Styling

<asm-map
  [geography]="worldData"
  fill="#457B9D"
  stroke="#1D3557"
  hoverFill="#2A4D6E"
  [tooltipConfig]="{ backgroundColor: '#1D3557', textColor: '#fff' }">
</asm-map>

Different Projections

<!-- Globe view -->
<asm-map [geography]="worldData" projection="geoOrthographic"></asm-map>

<!-- Mercator -->
<asm-map [geography]="worldData" projection="geoMercator"></asm-map>

<!-- Rotated orthographic (custom view) -->
<asm-map 
  [geography]="worldData" 
  projection="geoOrthographic"
  [projectionConfig]="{ rotate: [-10, -20] }">
</asm-map>

<!-- Centered on Asia -->
<asm-map 
  [geography]="worldData" 
  projection="geoEqualEarth"
  [projectionConfig]="{ center: [100, 30] }">
</asm-map>

Lines/Connections (Flight Paths)

import { MapComponent, MapLine } from 'ng-simple-maps';

lines: MapLine[] = [
  { from: [-74.006, 40.7128], to: [-0.1276, 51.5074], color: '#E91E63', curve: 0.4 },
  { from: [-74.006, 40.7128], to: [139.6917, 35.6895], color: '#3F51B5', curve: 0.5, dashed: true }
];

<asm-map
  [geography]="worldData"
  [lines]="lines"
  (lineClick)="onLineClick($event)">
</asm-map>

Choropleth Maps (Data Coloring)

import { MapComponent, ChoroplethData } from 'ng-simple-maps';

populationData: ChoroplethData = {
  'United States of America': 330,
  'China': 1400,
  'India': 1380,
  'Brazil': 212
};

<asm-map
  [geography]="worldData"
  [choroplethData]="populationData"
  [choroplethConfig]="{
    matchKey: 'name',
    colors: ['#FFF3E0', '#FFCC80', '#FFA726', '#F57C00', '#E65100'],
    nullColor: '#ECECEC'
  }">
</asm-map>

Graticule (Grid Lines)

<asm-map
  [geography]="worldData"
  projection="geoOrthographic"
  [showGraticule]="true"
  [graticuleConfig]="{ step: [15, 15], color: '#B3E5FC', opacity: 0.8 }">
</asm-map>

Country Labels

<asm-map
  [geography]="worldData"
  [showLabels]="true"
  [labelMinZoom]="2"
  [labelColor]="'#333'"
  [labelFontSize]="14"
  [zoomable]="true">
</asm-map>

Zoom to Feature

<asm-map
  [geography]="worldData"
  [zoomable]="true"
  [zoomOnClick]="true"
  [zoomOnClickLevel]="4"
  [zoomAnimationDuration]="1000">
</asm-map>

API Reference

MapComponent Inputs

Input	Type	Default	Description
`geography`	`string \| object`	required	Geography data URL or TopoJSON/GeoJSON object
`width`	`number`	`800`	Map width (for aspect ratio)
`height`	`number`	`400`	Map height (for aspect ratio)
`maxWidth`	`number`	`null`	Maximum width constraint
`projection`	`string`	`'geoEqualEarth'`	D3 projection type
`projectionConfig`	`ProjectionConfig`	`{}`	Projection configuration options
`continents`	`string \| string[]`	`null`	Filter by continent(s)
`fill`	`string`	`'#ECECEC'`	Geography fill color
`stroke`	`string`	`'#D6D6D6'`	Geography stroke color
`strokeWidth`	`number`	`0.5`	Geography stroke width
`hoverFill`	`string`	`null`	Fill color on hover
`markers`	`MapMarker[]`	`[]`	Array of markers
`annotations`	`MapAnnotation[]`	`[]`	Array of annotations
`markerColor`	`string`	`'#FF5533'`	Default marker color
`markerSize`	`number`	`6`	Default marker size
`lines`	`MapLine[]`	`[]`	Array of lines/connections
`lineColor`	`string`	`'#FF5533'`	Default line color
`lineStrokeWidth`	`number`	`2`	Default line stroke width
`choroplethData`	`ChoroplethData`	`null`	Data for coloring geographies
`choroplethConfig`	`ChoroplethConfig`	`null`	Choropleth styling config
`showGraticule`	`boolean`	`false`	Show grid lines
`graticuleConfig`	`GraticuleConfig`	`null`	Graticule styling config
`zoomable`	`boolean`	`false`	Enable zoom and pan
`showZoomControls`	`boolean`	`true`	Show zoom buttons
`minZoom`	`number`	`1`	Minimum zoom level
`maxZoom`	`number`	`8`	Maximum zoom level
`zoomOnClick`	`boolean`	`false`	Zoom to country on click
`zoomOnClickLevel`	`number`	`4`	Zoom level when clicking country
`zoomAnimationDuration`	`number`	`800`	Animation duration in milliseconds
`showTooltip`	`boolean`	`false`	Show tooltip on hover
`tooltipConfig`	`TooltipConfig`	`null`	Tooltip styling
`showLabels`	`boolean`	`false`	Show country labels
`labelMinZoom`	`number`	`1`	Minimum zoom level to show labels
`labelFontSize`	`number`	`12`	Label font size
`labelColor`	`string`	`'#333'`	Label text color
`labelFontWeight`	`string \| number`	`'normal'`	Label font weight

MapComponent Outputs

Output	Type	Description
`countryClick`	`MapGeographyEvent`	Emitted when a country is clicked
`countryHover`	`MapGeographyEvent`	Emitted when hovering over a country
`countryLeave`	`void`	Emitted when mouse leaves a country
`markerClick`	`MapMarkerEvent`	Emitted when a marker is clicked
`lineClick`	`MapLineEvent`	Emitted when a line is clicked

MapMarker Interface

interface MapMarker {
  coordinates: [number, number];  // [longitude, latitude]
  label?: string;                 // Optional label
  color?: string;                 // Fill color
  stroke?: string;                // Stroke color
  size?: number;                  // Size/radius (6-12 for icons, 16-24 for detailed SVGs)
  shape?: 'circle' | 'diamond' | 'pin' | 'star' | 'custom';
  customSvg?: string;             // SVG path data for shape='custom'
  customSvgSize?: number;         // ViewBox size for custom SVG (default: 24)
  data?: Record<string, unknown>; // Custom data
}

Custom SVG Markers

Three ways to use custom SVG icons as markers:

Option 1: Path Data Only (Recommended)

Just the d attribute value - most lightweight:

const AIRPLANE = 'M21,16V14L13,9V3.5A1.5,1.5,0,0,0,11.5,2...Z';

markers: MapMarker[] = [
  { coordinates: [-118.24, 34.05], shape: 'custom', customSvg: AIRPLANE, size: 10 }
];

Option 2: Full SVG Markup

For complex icons with multiple elements:

const PIN = `<svg viewBox="0 0 24 24">
  <path d="M12,2C8.13,2,5,5.13,5,9c0,5.25,7,13,7,13s7-7.75,7-13C19,5.13,15.87,2,12,2z"/>
  <circle cx="12" cy="9" r="2.5" fill="white"/>
</svg>`;

markers: MapMarker[] = [
  { coordinates: [121.47, 31.23], shape: 'custom', customSvg: PIN, size: 12 }
];

Option 3: Load from URL

Load SVG files from your assets folder:

markers: MapMarker[] = [
  { coordinates: [0, 0], shape: 'custom', customSvgUrl: '/assets/icons/marker.svg', size: 12 }
];

SVG Size Guidelines:

Use Case	`size`	Description
Small icons	6-8	Simple shapes
Standard	10-12	Recommended
Large/detailed	14-18	Fine details

Icon Set	`customSvgSize`
Material Design	24 (default)
Font Awesome	24
Custom 16px	16

MapAnnotation Interface

interface MapAnnotation {
  coordinates: [number, number];  // [longitude, latitude]
  text: string;                   // Label text
  dx?: number;                    // Horizontal offset (default: 30)
  dy?: number;                    // Vertical offset (default: -30)
  curve?: number;                 // Connector curve (0-1, default: 0)
  color?: string;                 // Text and connector color
  fontSize?: number;              // Font size
  fontWeight?: string | number;   // Font weight
}

TooltipConfig Interface

interface TooltipConfig {
  backgroundColor?: string;  // Default: '#fff'
  textColor?: string;        // Default: '#333'
  titleColor?: string;       // Default: same as textColor
  borderColor?: string;      // Default: '#ccc'
  borderRadius?: number;     // Default: 4
}

MapLine Interface

interface MapLine {
  from: [number, number];    // Starting [longitude, latitude]
  to: [number, number];      // Ending [longitude, latitude]
  color?: string;            // Line color
  strokeWidth?: number;      // Line thickness
  curve?: number;            // Arc height (0 = straight, higher = more curved)
  dashed?: boolean;          // Dashed line style
  data?: Record<string, unknown>; // Custom data
}

ChoroplethConfig Interface

interface ChoroplethConfig {
  matchKey?: string;      // Property to match (default: 'name')
  colors?: string[];      // Color scale from low to high
  minValue?: number;      // Override minimum value
  maxValue?: number;      // Override maximum value
  nullColor?: string;     // Color for missing data (default: '#ECECEC')
}

GraticuleConfig Interface

interface GraticuleConfig {
  step?: [number, number];  // Grid spacing in degrees (default: [10, 10])
  color?: string;           // Line color (default: '#ccc')
  strokeWidth?: number;     // Line thickness (default: 0.5)
  opacity?: number;         // Line opacity (default: 0.5)
}

ProjectionConfig Interface

interface ProjectionConfig {
  rotate?: [number, number, number?];  // Rotation angles [lambda, phi, gamma] in degrees
  center?: [number, number];           // Center coordinates [longitude, latitude]
  scale?: number;                      // Scale factor for the projection
  parallels?: [number, number];        // Standard parallels for conic projections
  translate?: [number, number];        // Translation offset [x, y]
  precision?: number;                  // Precision threshold for adaptive resampling
  clipAngle?: number;                  // Clipping angle for azimuthal projections
}

Available Projections

geoEqualEarth (default)
geoMercator
geoOrthographic
geoNaturalEarth1
geoAlbers
geoAlbersUsa
geoAzimuthalEqualArea
geoAzimuthalEquidistant
geoConicConformal
geoConicEqualArea
geoConicEquidistant
geoEquirectangular
geoGnomonic
geoStereographic
geoTransverseMercator

Continent Options

'Africa'
'Asia'
'Europe'
'North America'
'South America'
'Oceania'
'Antarctica'

TopoJSON Data Sources

World Atlas (Recommended)

Free, high-quality world country data maintained by Mike Bostock. Choose the right resolution for your use case:

CDN Links (Ready to Use)

// Fast loading (13KB) - for mobile apps and overview maps
worldData = 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json';

// Balanced quality (23KB) - recommended for web apps
worldData = 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-50m.json';

// High detail (94KB) - for detailed maps and print quality
worldData = 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-10m.json';

Resolution Guide

Resolution	File Size	Use Case	Best For
110m	13KB	Fast loading	Mobile apps, overview maps, low bandwidth
50m	23KB	Recommended	Web applications, general purpose
10m	94KB	High detail	Desktop apps, print quality, detailed viewing

Available Files

countries-110m.json - Low resolution, fast loading
countries-50m.json - Medium resolution, balanced (used in all demos)
countries-10m.json - High resolution, detailed

Other Data Sources

World Atlas GitHub - Source repository
Natural Earth - Free map data in various formats
TopoJSON Collection - Various geographic datasets

Local Files

You can also download and serve TopoJSON files from your own assets folder:

// From local assets
worldData = '/assets/data/countries-50m.json';

License

MIT

Credits

Inspired by react-simple-maps. Built with D3 Geo.