syncfusion-angular-maps

# Implementing Syncfusion Angular Maps Comprehensive guide for implementing the Syncfusion Angular Maps component to visualize geographical data with interactive features, multiple layers, and rich customization options. ## When to Use This Skill Use this skill when you need to: - **Visualize geographical data** - Display statistical data on world maps, country maps, regional maps, or custom geographic shapes - **Create interactive maps** - Build maps with zoom, pan, selection, highlighting, and tooltip interactions - **Plot locations** - Add markers, bubbles, or annotations to highlight specific geographic points - **Display map layers** - Work with multiple overlapping layers using GeoJSON data or map providers (Bing, OpenStreetMap, Azure) - **Color-code regions** - Apply color mapping based on data values for choropleth/heat map visualizations - **Custom map visualizations** - Create non-geographic visualizations like seat layouts, floor plans, or stadium maps - **Navigation and routing** - Draw navigation lines or routes between markers - **Export and print maps** - Generate printable or exportable map visualizations - **Build dashboards** - Integrate maps into Angular applications for business intelligence or analytics ## Component Overview The Syncfusion Angular Maps component (`@syncfusion/ej2-angular-maps`) is a powerful data visualization tool that renders geographical data using Scalable Vector Graphics (SVG). It supports: - **Multiple layers and sublayers** for complex visualizations - **GeoJSON data binding** for custom shapes and regions - **Map providers** (Bing Maps, OpenStreetMap, Azure Maps) as base layers - **Six projection types** (Mercator, Equirectangular, Miller, Eckert3, Eckert5, Eckert6, Winkel3, AitOff) - **Rich visualization elements** - markers, bubbles, data labels, legends, navigation lines, annotations - **Interactive features** - zooming, panning, tooltips, selection, highlighting - **Responsive and accessible** design with WCAG compliance ## Documentation and Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) When implementing Maps for the first time or setting up a new Angular project: - Installing dependencies (@syncfusion/ej2-angular-maps package) - Setting up Angular environment and importing MapsModule - Creating first basic map with world map data - Understanding module injection for features (MarkerService, BubbleService, etc.) - Adding CSS themes and styling - Running the application ### Layers and Data Binding 📄 **Read:** [references/layers-and-data.md](references/layers-and-data.md) For working with map layers, shape data, and data source binding: - Understanding layer structure and configuration - Loading GeoJSON shape data (shapeData property) - Binding external data sources (dataSource, shapeDataPath, shapePropertyPath) - Creating multiple layers and sublayers - Layer types (base layer vs sublayer) - Switching between layers (baseLayerIndex) - Rendering custom shapes for non-geographic visualizations - GeometryType options (Geographic vs Normal) ### Markers 📄 **Read:** [references/markers.md](references/markers.md) For adding and customizing location markers: - Adding markers with latitude/longitude data - Marker shapes (Balloon, Circle, Cross, Diamond, Image, Rectangle, Star, Triangle) - Custom marker templates - Marker styling (size, color, border, opacity) - Dynamic markers with data binding - Marker clustering - Marker animations and transitions - Marker tooltips and events - Creating routes between markers ### Data Visualization Features 📄 **Read:** [references/data-visualization.md](references/data-visualization.md) For visualizing data with bubbles, colors, labels, and legends: - **Bubbles** - Size-based visualization for quantitative data - **Color mapping** - Range color mapping, equal color mapping, desaturation color mapping - **Data labels** - Displaying shape names or data values on the map - **Legends** - Adding legends for color mapping and bubbles - **Navigation lines** - Drawing lines between locations - **Annotations** - Adding custom HTML content at specific positions - Combining multiple visualization features ### User Interactions 📄 **Read:** [references/user-interactions.md](references/user-interactions.md) For implementing interactive map behaviors: - **Zooming** - Mouse wheel zoom, pinch zoom, double-click zoom, zoom toolbar - **Panning** - Mouse drag and touch panning - **Tooltips** - Layer tooltips, marker tooltips, bubble tooltips - **Selection** - Shape selection, marker selection, bubble selection - **Highlighting** - Hover highlight effects - **Interactive legend** - Clicking legend items to show/hide shapes - Event handling (click, hover, zoom, pan events) - Touch and mobile support ### Map Providers 📄 **Read:** [references/map-providers.md](references/map-providers.md) For integrating external map services: - Overview of map provider support - **Bing Maps** integration and API key configuration - **OpenStreetMap** (OSM) integration - **Azure Maps** integration - Provider-specific features and limitations - Combining map providers with shape layers - URL templates and tile services - Zoom level configuration ### Polygon Shapes 📄 **Read:** [references/polygon-shapes.md](references/polygon-shapes.md) For drawing and customizing polygons: - Adding polygon overlays to maps - Polygon configuration and data structure - Styling polygons (fill, border, opacity) - Polygon events (click, hover) - Use cases (highlighting regions, boundaries, zones) - Dynamic polygon rendering ### Customization and Styling 📄 **Read:** [references/customization.md](references/customization.md) For theming and visual customization: - CSS customization and theme overrides - Shape styling (fill, border, color schemes) - Responsive design patterns - **Map projections** - Choosing and configuring projection types - Background customization (colors, images) - Title and subtitle styling - Border and margin configuration ### Localization and Internationalization 📄 **Read:** [references/localization.md](references/localization.md) For globalizing map content: - Internationalization (i18n) setup - Localization (l10n) for different languages - Right-to-left (RTL) support - Number formatting for different locales - Currency formatting in tooltips/labels - Date and time formatting - Culture-specific rendering ### Advanced Features 📄 **Read:** [references/advanced-features.md](references/advanced-features.md) For advanced capabilities and APIs: - **Print and Export** - Printing maps, exporting to PNG/JPEG/SVG/PDF - **State persistence** - Saving and restoring map state - **Public methods** - Programmatic control (refresh, print, export, etc.) - **Events reference** - Complete list of available events - **Creating routes** - Drawing navigation routes between markers - **Custom path rendering** - Advanced path and line customization - **Drilldown navigation** - Creating hierarchical map navigation ### Accessibility 📄 **Read:** [references/accessibility.md](references/accessibility.md) For accessible map implementations: - WCAG 2.1 compliance guidelines - Keyboard navigation support - ARIA attributes and roles - Screen reader compatibility - High contrast theme support - Focus indicators and management - Alternative text for shapes and markers ## Quick Start ### Installation ```bash # Install the Maps package npm install @syncfusion/ej2-angular-maps --save ``` ### Basic Implementation ```typescript import { Component } from '@angular/core'; import { MapsModule } from '@syncfusion/ej2-angular-maps'; import { world_map } from './world-map'; // GeoJSON data @Component({ selector: 'app-root', standalone: true, imports: [MapsModule], template: ` <ejs-maps id='maps-container'> <e-layers> <e-layer [shapeData]='shapeData'></e-layer> </e-layers> </ejs-maps> ` }) export class AppComponent { public shapeData: object = world_map; } ``` ### With Data Binding and Color Mapping ```typescript import { Component } from '@angular/core'; import { MapsModule } from '@syncfusion/ej2-angular-maps'; import { world_map } from './world-map'; @Component({ selector: 'app-root', standalone: true, imports: [MapsModule], template: ` <ejs-maps id='maps-container'> <e-layers> <e-layer [shapeData]='shapeData' [dataSource]='dataSource' shapeDataPath='Country' shapePropertyPath='name' [shapeSettings]='shapeSettings'> </e-layer> </e-layers> </ejs-maps> ` }) export class AppComponent { public shapeData: object = world_map; public dataSource: object[] = [ { Country: 'United States', Population: 331002651, Code: 'US' }, { Country: 'India', Population: 1380004385, Code: 'IN' }, { Country: 'China', Population: 1439323776, Code: 'CN' } ]; public shapeSettings: object = { colorValuePath: 'Population', colorMapping: [ { from: 0, to: 100000000, color: '#C5E8B7' }, { from: 100000001, to: 500000000, color: '#5BC85A' }, { from: 500000001, to: 2000000000, color: '#238B45' } ] }; } ``` ## Common Patterns ### Pattern 1: Map with Markers and Tooltips ```typescript import { Component } from '@angular/core'; import { MapsModule, MarkerService, MapsTooltipService } from '@syncfusion/ej2-angular-maps'; import { world_map } from './world-map'; @Component({ selector: 'app-root', standalone: true, imports: [MapsModule], providers: [MarkerService, MapsTooltipService], template: ` <ejs-maps id='maps-container'> <e-layers> <e-layer [shapeData]='shapeData' [markerSettings]='markerSettings'> </e-layer> </e-layers> </ejs-maps> ` }) export class AppComponent { public shapeData: object = world_map; public markerSettings: object[] = [{ visible: true, dataSource: [ { latitude: 40.7128, longitude: -74.0060, name: 'New York' }, { latitude: 51.5074, longitude: -0.1278, name: 'London' }, { latitude: 35.6762, longitude: 139.6503, name: 'Tokyo' } ], shape: 'Circle', fill: '#FF6347', height: 15, width: 15, tooltipSettings: { visible: true, valuePath: 'name' } }]; } ``` ### Pattern 2: Interactive Map with Zoom and Legend ```typescript import { Component } from '@angular/core'; import { MapsModule, ZoomService, LegendService } from '@syncfusion/ej2-angular-maps'; import { world_map } from './world-map'; @Component({ selector: 'app-root', standalone: true, imports: [MapsModule], providers: [ZoomService, LegendService], template: ` <ejs-maps id='maps-container' [zoomSettings]='zoomSettings' [legendSettings]='legendSettings'> <e-layers> <e-layer [shapeData]='shapeData' [dataSource]='dataSource' shapeDataPath='Country' shapePropertyPath='name' [shapeSettings]='shapeSettings'> </e-layer> </e-layers> </ejs-maps> ` }) export class AppComponent { public shapeData: object = world_map; public dataSource: object[] = [ { Country: 'United States', Category: 'High' }, { Country: 'Canada', Category: 'Medium' }, { Country: 'Mexico', Category: 'Low' } ]; public shapeSettings: object = { colorValuePath: 'Category', colorMapping: [ { value: 'High', color: '#E74C3C' }, { value: 'Medium', color: '#F39C12' }, { value: 'Low', color: '#27AE60' } ] }; public zoomSettings: object = { enable: true, toolbars: ['Zoom', 'ZoomIn', 'ZoomOut', 'Pan', 'Reset'] }; public legendSettings: object = { visible: true, position: 'Bottom' }; } ``` ### Pattern 3: Multi-Layer Map with Sublayers ```typescript import { Component } from '@angular/core'; import { MapsModule } from '@syncfusion/ej2-angular-maps'; import { world_map } from './world-map'; import { usa_map } from './usa-map'; import { california } from './california'; @Component({ selector: 'app-root', standalone: true, imports: [MapsModule], template: ` <ejs-maps id='maps-container'> <e-layers> <!-- Base layer --> <e-layer [shapeData]='usaMap' [shapeSettings]='baseShapeSettings'> </e-layer> <!-- Sublayer highlighting California --> <e-layer type='SubLayer' [shapeData]='californiaMap' [shapeSettings]='sublayerShapeSettings'> </e-layer> </e-layers> </ejs-maps> ` }) export class AppComponent { public usaMap: object = usa_map; public californiaMap: object = california; public baseShapeSettings: object = { fill: '#E5E5E5', border: { color: '#000000', width: 0.5 } }; public sublayerShapeSettings: object = { fill: '#FFD700', border: { color: '#FF6347', width: 2 } }; } ``` ## Key Configuration Options ### Layer Settings - `shapeData` - GeoJSON data for shapes - `dataSource` - External data to bind - `shapeDataPath` - Field in dataSource identifying shape - `shapePropertyPath` - Field in shapeData matching dataSource - `shapeSettings` - Visual styling for shapes