Getting started in EJ2 TypeScript Maps control

7 May 202524 minutes to read

This section briefly explains how to createMaps component and configure its available functionalities in TypeScript using the Essential^® JS 2quickstart seed repository.

This application is integrated with thewebpack.config.js configuration and uses the latest version of thewebpack-cli. It requires nodev14.15.0 or higher. For more information about webpack and its features, refer to thewebpack documentation.

You can explore some useful features in the Maps control using the following video.

Dependencies

Below is the list of minimum dependencies required to use the Maps.

|--@syncfusion/ej2-maps|--@syncfusion/ej2-base|--@syncfusion/ej2-data|--@syncfusion/ej2-pdf-export|--@syncfusion/ej2-svg-base

Set up development environment

Open the command prompt from the required directory, and run the following command to clone the Syncfusion^® JavaScript (Essential^® JS 2) quickstart project fromGitHub.

git clone https://github.com/SyncfusionExamples/ej2-quickstart-webpack- ej2-quickstart

After cloning the application in theej2-quickstart folder, run the following command line to navigate to theej2-quickstart folder.

cd ej2-quickstart

Add Syncfusion^® JavaScript packages

Syncfusion^® JavaScript (Essential^® JS 2) packages are available on thenpmjs.com public registry. You can install all Syncfusion^® JavaScript (Essential^® JS 2) controls in a single@syncfusion/ej2 package or individual packages for each control.

The quickstart application is preconfigured with the dependent@syncfusion/ej2 package in the~/package.json file. Use the following command to install the dependent npm packages from the command prompt.

npm install

Add Map control to the Project

The Essential^® JS2 Maps control can be added to the application. To get started, add the Maps control to theapp.ts andindex.html files using the following code.

Add an HTML div element to act as the Maps element in theindex.html file using the following code.

index.html

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/></head><body><!--container which is going to render the Map--><divid='container'></div></body></html>

Import the Maps control in theapp.ts to initialize a Maps and append the Maps instance to the#container.

app.ts

import{Maps}from'@syncfusion/ej2-maps';// initialize Maps componentletmap:Maps=newMaps();// render initialized Mapmap.appendTo('#container');

The quickstart project is configured to compile and run the application in the browser. Use the following command to run the application.

npm start

As we didn’t specify shapeData to the maps, no shape will be rendered and only an empty SVG element is appended to the maps container.

Module Injection

Maps component are segregated into individual feature-wise modules. In order to use a particular feature,
you need to inject its feature module usingMaps.Inject() method. Find the modules available in maps and its description as follows.

Annotations - Inject this provider to use annotations feature.
Bubble - Inject this provider to use bubble feature.
DataLabel - Inject this provider to use data label feature.
Highlight - Inject this provider to use highlight feature.
Legend - Inject this provider to use legend feature.
Marker - Inject this provider to use marker feature.
MapsTooltip - Inject this provider to use tooltip series.
NavigationLine - Inject this provider to use navigation lines feature.
Selection - Inject this provider to use selection feature.
Zoom - Inject this provider to use zooming and panning feature.

In the current application, we are going to modify the above basic maps to visualize 2016 USA president election results.

For this application we are going to use tooltip, data label and legend features of the maps.

Now import the MapsTooltip, DataLabel and Legend modules from maps package and inject it into the Maps component usingMaps.Inject method.

app.ts

import{Maps,Legend,DataLabel,MapsTooltip}from'@syncfusion/ej2-maps';Maps.Inject(Legend,DataLabel,MapsTooltip);

Render shapes from GeoJSON data

This section explains how to bind GeoJSON data to the map.

letusMap:Object={"type":"FeatureCollection","crs":{"type":"name","properties":{"name":"urn:ogc:def:crs:OGC:1.3:CRS84"}},"features":[{"type":"Feature","properties":{"iso_3166_2":"MA","name":"Massachusetts","admin":"United States of America"},"geometry":{"type":"MultiPolygon","coordinates":[[[[-70.801756294617277,41.248076234530558]]]]}}]//..};

exportletworld_map:object={"type":"FeatureCollection","crs":{"type":"name","properties":{"name":"urn:ogc:def:crs:OGC:1.3:CRS84"}},"features":[{"type":"Feature","properties":{"admin":"Afghanistan","name":"Afghanistan","continent":"Asia"},...};<!--markdownlint-disableMD009-->

Elements in the maps will get rendered in the layers. So add a layer collection to the maps by usinglayers property. Now bind the GeoJSON data to theshapeData property.

index.ts
index.html

import{Maps}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';letmap:Maps=newMaps({layers:[{shapeData:world_map}]});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Note: Refer the data values forworld_map here.

Bind data source to map

The following properties in layers are used for binding data source to map.

dataSource
shapeDataPath
shapePropertyPath

ThedataSource property takes collection value as input. For example, the list of objects can be provided as input. This data is further used in tooltip, data label, bubble, legend and in color mapping.

TheshapeDataPath property used to refer the data ID in dataSource. Where as, theshapePropertyPath property is used to refer the column name in shapeData to identify the shape. Both the properties are related to each other. When the values of the shapeDataPath property in the dataSource property and the value of shapePropertyPath in the shapeData property match, then the associated object from the dataSource is bound to the corresponding shape.

The JSON object “electionData” is used as data source below.

index.ts
index.html

import{Maps}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';letmap:Maps=newMaps({layers:[{shapeData:world_map,dataSource:[{"Country":"China","Membership":"Permanent"},{"Country":"France","Membership":"Permanent"},{"Country":"Russia","Membership":"Permanent"},{"Country":"Kazakhstan","Membership":"Non-Permanent"},{"Country":"Poland","Membership":"Non-Permanent"},{"Country":"Sweden","Membership":"Non-Permanent"}],shapePropertyPath:'name',shapeDataPath:'Country'}]});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Note: Refer the data values forworld_map here.

Apply Color Mapping

The Color Mapping feature supports customization of shape colors based on the underlying value of shape received from bounded data. Specify the field name from which the values have to be compared for the shapes incolorValuePath property inshapeSettings.

Specify color and value incolorMapping property. Here ‘#D84444’ is specified for ‘Trump’ and ‘#316DB5’ is specified for ‘Clinton’.

index.ts
index.html

//tslint:disableimport{Maps}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';letmap:Maps=newMaps({layers:[{shapeData:world_map,dataSource:[{"Country":"China","Membership":"Permanent"},{"Country":"France","Membership":"Permanent"},{"Country":"Russia","Membership":"Permanent"},{"Country":"Kazakhstan","Membership":"Non-Permanent"},{"Country":"Poland","Membership":"Non-Permanent"},{"Country":"Sweden","Membership":"Non-Permanent"}],shapePropertyPath:'name',shapeDataPath:'Country',colorValuePath:'Membership',shapeSettings:{colorValuePath:'Membership',colorMapping:[{value:'Permanent',color:'#D84444'},{value:'Non-Permanent',color:'#316DB5'}]}}]});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Add Title for Maps

You can add a title usingtitleSettings property to the map to provide quick information to the user about the shapes rendered in the map.

index.ts
index.html

//tslint:disableimport{Maps}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';letmap:Maps=newMaps({titleSettings:{text:'USA Election Results - 2016'},layers:[{shapeData:world_map,dataSource:[{"Country":"China","Membership":"Permanent"},{"Country":"France","Membership":"Permanent"},{"Country":"Russia","Membership":"Permanent"},{"Country":"Kazakhstan","Membership":"Non-Permanent"},{"Country":"Poland","Membership":"Non-Permanent"},{"Country":"Sweden","Membership":"Non-Permanent"}],shapePropertyPath:'name',shapeDataPath:'Country',shapeSettings:{colorValuePath:'Membership',colorMapping:[{value:'Permanent',color:'#D84444'},{value:'Non-Permanent',color:'#316DB5'}]}}]});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Enable Legend

You can show legend for the maps by setting true to thevisible property inlegendSettings object and by injecting theLegend module usingMaps.Inject(Legend) method.

index.ts
index.html

import{Maps,Legend}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';Maps.Inject(Legend);letmap:Maps=newMaps({layers:[{titleSettings:{text:'USA Election Results - 2016'},shapeData:world_map,dataSource:[{"Country":"China","Membership":"Permanent"},{"Country":"France","Membership":"Permanent"},{"Country":"Russia","Membership":"Permanent"},{"Country":"Kazakhstan","Membership":"Non-Permanent"},{"Country":"Poland","Membership":"Non-Permanent"},{"Country":"Sweden","Membership":"Non-Permanent"}],shapePropertyPath:'name',shapeDataPath:'Country',shapeSettings:{colorValuePath:'Membership',colorMapping:[{value:'Permanent',color:'#D84444'},{value:'Non-Permanent',color:'#316DB5'}]}}],legendSettings:{visible:true}});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Add Data Label

You can add data labels to show additional information of the shapes in map. This can be achieved by settingvisible property to true in thedataLabelSettings object and by injectingDataLabel module usingMaps.Inject(DataLabel) method.

index.ts
index.html

import{Maps,Legend,DataLabel}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';Maps.Inject(Legend,DataLabel);letmap:Maps=newMaps({layers:[{shapeData:world_map,shapeSettings:{autofill:true},dataLabelSettings:{visible:true,labelPath:'name',smartLabelMode:'Trim'}}]});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Enable Tooltip

The tooltip is useful when you cannot display information by using the data labels due to space constraints. You can enable tooltip by setting thevisible property as true intooltipSettings object and by injectingMapsTooltip module usingMaps.Inject(MapsTooltip) method.

index.ts
index.html

import{Maps,DataLabel,MapsTooltip}from'@syncfusion/ej2-maps';import{world_map}from'./world-map.ts';Maps.Inject(DataLabel,MapsTooltip);letmap:Maps=newMaps({layers:[{shapeData:world_map,shapeSettings:{autofill:true},dataLabelSettings:{visible:true,labelPath:'name',smartLabelMode:'Trim'},tooltipSettings:{visible:true,valuePath:'name'}}]});map.appendTo('#element');

<!DOCTYPE html><htmllang="en"><head><title>EJ2 Maps</title><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="description"content="Typescript UI Controls"/><metaname="author"content="Syncfusion"/><linkhref="index.css"rel="stylesheet"/><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script><scriptsrc="world-map.js"></script><scriptsrc="systemjs.config.js"></script><scriptsrc="https://cdn.syncfusion.com/ej2/syncfusion-helper.js"type="text/javascript"></script></head><body><divid='loader'>Loading....</div><divid='container'style="height: 500px; width: 700px"><divid='element'></div></div></body></html>

Help us improve this page

Correct inaccurate or outdated content