ng-simple-maps


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
- 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

``bash
npm install ng-simple-maps
`

Quick Start

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

@Component({
imports: [MapComponent],
template:
[geography]="worldData"
[zoomable]="true"
[showTooltip]="true">


})
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

$3

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

@Component({
imports: [MapComponent],
template:
[geography]="worldData"
[markers]="markers"
[zoomable]="true"
[showTooltip]="true"
(markerClick)="onMarkerClick($event)">


})
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);
}
}
`

$3

`typescript
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 }
];
`

`html
[geography]="worldData"
[markers]="markers"
[annotations]="annotations">

`

$3

`html





`

$3

`html
[geography]="worldData"
fill="#457B9D"
stroke="#1D3557"
hoverFill="#2A4D6E"
[tooltipConfig]="{ backgroundColor: '#1D3557', textColor: '#fff' }">

`

$3

`html




[geography]="worldData"
projection="geoOrthographic"
[projectionConfig]="{ rotate: [-10, -20] }">



[geography]="worldData"
projection="geoEqualEarth"
[projectionConfig]="{ center: [100, 30] }">

`

$3

`typescript
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 }
];
`

`html
[geography]="worldData"
[lines]="lines"
(lineClick)="onLineClick($event)">

`

$3

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

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

`html
[geography]="worldData"
[choroplethData]="populationData"
[choroplethConfig]="{
matchKey: 'name',
colors: ['#FFF3E0', '#FFCC80', '#FFA726', '#F57C00', '#E65100'],
nullColor: '#ECECEC'
}">

`

$3

`html
[geography]="worldData"
projection="geoOrthographic"
[showGraticule]="true"
[graticuleConfig]="{ step: [15, 15], color: '#B3E5FC', opacity: 0.8 }">

`

$3

`html
[geography]="worldData"
[showLabels]="true"
[labelMinZoom]="2"
[labelColor]="'#333'"
[labelFontSize]="14"
[zoomable]="true">

`

$3

`html
[geography]="worldData"
[zoomable]="true"
[zoomOnClick]="true"
[zoomOnClickLevel]="4"
[zoomAnimationDuration]="1000">

`

API Reference

$3

| 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 |

$3

| 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 |

$3

`typescript
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; // Custom data
}
`

$3

Three ways to use custom SVG icons as markers:

#### Option 1: Path Data Only (Recommended)
Just the d attribute value - most lightweight:

`typescript
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:

`typescript
const PIN =


;

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:

`typescript
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 |

$3

`typescript
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
}
`

$3

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

$3

`typescript
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; // Custom data
}
`

$3

`typescript
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')
}
`

$3

`typescript
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)
}
`

$3

`typescript
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
}
`

$3

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

$3

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

TopoJSON Data Sources

$3

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

#### CDN Links (Ready to Use)
`typescript
// 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

$3

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

License

MIT

Credits

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