syncfusion-javascript-maps

# Implementing Syncfusion Maps in TypeScript and JavaScript The Syncfusion EJ2 Maps component visualizes geographic information through online tile providers, GeoJSON shape layers, markers, bubbles, custom polygons, navigation lines, labels, legends, annotations, tooltips, selection, zooming, panning, printing, and exporting. This skill covers framework-neutral implementations for: - TypeScript applications using npm and module imports. - JavaScript applications using a versioned EJ2 global bundle. - OpenStreetMap and authenticated map providers. - GeoJSON geographic shapes. - Coordinate-based markers. - Region-bound bubbles. - Custom polygon overlays. - Shape and bubble color mapping. - Navigation lines. - Legends, annotations, and tooltips. - Selection and highlighting. - Built-in and application-owned persistence. - Printing and image export. - Accessibility, validation, performance, and cleanup. ## Platform Support ### TypeScript Use TypeScript when the application uses: - The `@syncfusion/ej2-maps` npm package. - TypeScript compilation. - Webpack, Vite, or another module bundler. - Explicit feature-module injection. - Strongly typed data and configuration models. - Compile-time validation and IDE IntelliSense. Install the package: ```bash npm install @syncfusion/ej2-maps ``` Basic import: ```typescript import { Maps } from '@syncfusion/ej2-maps'; ``` Feature modules must be imported and injected before constructing Maps. ```typescript import { Maps, Marker, Zoom } from '@syncfusion/ej2-maps'; Maps.Inject( Zoom, Marker ); ``` ### JavaScript Use global JavaScript when the application uses: - A versioned EJ2 CDN bundle. - A locally hosted EJ2 global bundle. - Traditional HTML and JavaScript files. - The global `ej.maps.Maps` constructor. - No TypeScript compilation. Global constructor: ```javascript ej.maps.Maps ``` Use the complete versioned EJ2 global bundle: ```html <script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script> ``` Do not mix the complete bundle with separate `ej2-base`, `ej2-data`, `ej2-svg-base`, and `ej2-maps` scripts. Global JavaScript using the complete bundle does not require explicit `Maps.Inject(...)` calls. ### JavaScript Compatibility The global JavaScript examples use ES5-compatible syntax where practical: ```text var declarations Traditional functions No TypeScript annotations No ECMAScript module imports Global ej namespace ``` Browser support must still match the supported-browser matrix of the installed EJ2 release. Do not promise unrestricted legacy-browser compatibility. ## When to Use This Skill Use this skill when the task requires: - Rendering an online map provider. - Rendering countries, states, or custom regions from GeoJSON. - Displaying coordinate-based locations. - Visualizing regional magnitude with bubbles. - Applying data-driven shape or bubble colors. - Drawing custom coordinate-defined polygon areas. - Connecting locations with navigation lines. - Adding data labels to geographic shapes. - Displaying legends and tooltips. - Adding map-relative annotation content. - Selecting or highlighting shapes, markers, or bubbles. - Supporting zooming and panning. - Persisting supported map state. - Storing validated application preferences. - Printing the rendered map. - Exporting the map as PNG, JPEG, or SVG. - Supporting responsive layouts. - Optimizing large geographic datasets. - Diagnosing setup, network, data-binding, or rendering failures. ## Visualization Selection Guide ### Use Markers Use markers for locations defined directly by latitude and longitude. Examples: - Offices. - Stores. - Airports. - Warehouses. - Incident points. - Route waypoints. ### Use Bubbles Use bubbles for numeric values associated with GeoJSON shapes. Examples: - Population by country. - Revenue by state. - Sales by territory. - Engagement by region. Bubbles are not direct replacements for coordinate markers. ### Use GeoJSON Shapes Use `shapeData` for: - Countries. - States. - Provinces. - Districts. - Administrative boundaries. - Custom geographic feature collections. ### Use Custom Polygons Use `polygonSettings.polygons` for application-defined areas based on coordinate points. Examples: - Delivery zones. - Restricted regions. - Coverage areas. - Service boundaries. ### Use Navigation Lines Use navigation lines to display: - Routes. - Journeys. - Connections. - Flight paths. - Geographic dependencies. ## Feature Module Reference ```text Zooming and panning -> Zoom Markers -> Marker Bubbles -> Bubble Navigation lines -> NavigationLine Tooltips -> MapsTooltip Legends -> Legend Annotations -> Annotations Selection -> Selection Data labels -> DataLabel Custom polygons -> Polygon Printing -> Print Image export -> ImageExport PDF export -> PdfExport ``` Import and inject only the modules used by an example. Example: ```typescript import { Maps, MapsTooltip, Marker, Zoom } from '@syncfusion/ej2-maps'; Maps.Inject( Zoom, Marker, MapsTooltip ); ``` Keep imports and injection synchronized. Incorrect: ```typescript import { Maps } from '@syncfusion/ej2-maps'; Maps.Inject( Marker ); ``` Correct: ```typescript import { Maps, Marker } from '@syncfusion/ej2-maps'; Maps.Inject( Marker ); ``` ## Implementation Rules ### Use Explicit DOM Attachment Preferred TypeScript: ```typescript const map: Maps = new Maps({ layers }); map.appendTo( '#maps-container' ); ``` Preferred JavaScript: ```javascript var map = new ej.maps.Maps({ layers: layers }); map.appendTo( '#maps-container' ); ``` ### Verify the Host Element ```typescript const host: HTMLElement | null = document.getElementById( 'maps-container' ); if (!host) { throw new Error( 'The Maps host element "#maps-container" was not found.' ); } ``` ### Provide Measurable Dimensions ```css #maps-container { width: 100%; min-height: 600px; } ``` Configure Maps with a definite height: ```typescript width: '100%', height: '600px' ``` Avoid relying on: ```typescript height: '100%' ``` unless every relevant ancestor has a definite computed height. ### Use centerPosition Incorrect: ```typescript center: { latitude: 37.7749, longitude: -122.4194 } ``` Correct: ```typescript centerPosition: { latitude: 37.7749, longitude: -122.4194 } ``` ### Keep Feature Configuration at the Correct Level ```text Shape data -> Layer shapeData Shape binding data -> Layer dataSource Shape tooltip -> Layer tooltipSettings Shape selection -> Layer selectionSettings Markers -> Layer markerSettings array Marker tooltip -> Marker entry tooltipSettings Marker selection -> Marker entry selectionSettings Bubbles -> Layer bubbleSettings array Bubble tooltip -> Bubble entry tooltipSettings Bubble selection -> Bubble entry selectionSettings Navigation lines -> Layer navigationLineSettings array Custom polygons -> Layer polygonSettings Shape labels -> Layer dataLabelSettings ``` ## Documentation and Navigation Guide ### Getting Started and Setup Read: ```text references/getting-started.md ``` Use this reference for: - Package installation. - TypeScript imports. - Module injection. - JavaScript CDN setup. - OpenStreetMap initialization. - Host dimensions. - World-map data acquisition. - First Maps implementation. ### Data and Layers Read: ```text references/data-and-layers.md ``` Use this reference for: - Online tile layers. - GeoJSON shape layers. - Main layers. - Sublayers. - `baseLayerIndex`. - Shape data binding. - Marker and bubble data placement. - Layer visibility. - Safe runtime updates. ### Markers and Navigation Read: ```text references/markers-and-navigation.md ``` Use this reference for: - Coordinate-based markers. - Marker appearance. - Marker templates. - Marker images. - Marker tooltips. - Marker selection. - Marker events. - Marker clustering. - Navigation lines. - Dynamic marker and route updates. ### Visualization Features Read: ```text references/visualization-features.md ``` Use this reference for: - Region-bound bubbles. - GeoJSON shape rendering. - Custom polygon overlays. - Shape color mapping. - Bubble color mapping. - Shape data labels. - Combined regional visualizations. ### Legends and Annotations Read: ```text references/legends-and-annotations.md ``` Use this reference for: - Default and Interactive legends. - Docked and floating legends. - Layer, marker, and bubble legends. - Legend toggle behavior. - Map-relative annotations. - Shape, marker, and bubble tooltips. ### Map Providers and Selection Read: ```text references/map-providers-and-selection.md ``` Use this reference for: - OpenStreetMap. - Bing Maps. - Custom tile providers. - Provider authentication. - Provider security and attribution. - Shape selection. - Marker selection. - Bubble selection. - Single and multiple selection. - Validated interaction events. ### Customization and Persistence Read: ```text references/customization-and-persistence.md ``` Use this reference for: - Built-in themes. - Public appearance models. - Application-owned wrapper CSS. - Responsive layouts. - Built-in persistence. - Validated browser-storage preferences. - Printing. - PNG, JPEG, and SVG export. - Cleanup. ### Troubleshooting Read: ```text references/troubleshooting.md ``` Use this reference for: - Installation failures. - Bundle-loading failures. - Missing module injection. - Host and dimension problems. - Tile-provider failures. - GeoJSON loading failures. - Marker and bubble issues. - Data-binding problems. - Color-mapping failures. - Tooltip and selection issues. - Performance and memory problems. - TypeScript and JavaScript diagnostics. ## TypeScript Quick Start This example renders OpenStreetMap with a marker, marker tooltip, zooming, and panning. ### index.html ```html <!doctype html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" > <title>Syncfusion Maps</title> ./styles.css </head> <body> <main class="page-container"> <section class="maps-card" aria-labelledby="maps-heading" aria-describedby="maps-description" > <h1 id="maps-heading"> Office Location </h1> <p id="maps-description"> An interactive OpenStreetMap view showing the San Francisco office location. </p> <div id="maps-container"></div> <p class="map-attribution"> Map data © OpenStreetMap contributors </p> <p id="maps-status" aria-live="polite" > Loading the map. </p> </section> </main> <script scr="app.ts"></script> </body> </html> ``` ### styles.css ```css html, body { margin: 0; min-height: 100%; } body { color: #111827; background: #f1f5f9; font-family: "Segoe UI", Arial, sans-serif; } .page-container { width: 100%; min-height: 100vh; padding: 24px; box-sizing: border-box; } .maps-card { width: 100%; max-width: 1200px; margin: 0 auto; padding: 16px; box-sizing: border-box; background: #ffffff; border: 1px solid #cbd5e1; border-radius: 8px; } .maps-card h1 { margin: 0 0 8px; font-size: 24px; } .maps-card > p { color: #475569; line-height: 1.5; } #maps-container { width: 100%; min-height: 600px; } .map-attribution { margin: 8px 0 0; font-size: 12px; } @media (max-width: 768px) { .page-container { padding: 12px; } .maps-card { padding: 12px; } #maps-container { min-height: 500px; } } ``` ### app.ts ```typescript import { Maps, MapsTooltip, Marker, Zoom } from '@syncfusion/ej2-maps'; Maps.Inject( Zoom, Marker, MapsTooltip ); interface LocationData { id: string; name: string; latitude: number; longitude: number; } const locationData: LocationData[] = [ { id: 'san-francisco-office', name: 'San Francisco Office', latitude: 37.7749, longitude: -122.4194 } ]; const validateLocations = ( locations: LocationData[]