Getting Started

This section explains you the steps required to create a map and demonstrate the basic usage of the maps control.

Dependencies

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

|-- @syncfusion/ej2-maps
    |-- @syncfusion/ej2-base
    |-- @syncfusion/ej2-buttons
    |-- @syncfusion/ej2-popups

Installation and Configuration

  • To get started with Maps component, you can clone the Essential JS 2 quickstart project and install necessary packages by using the following commands.
git clone https://github.com/syncfusion/ej2-quickstart.git quickstart
cd quickstart
npm install
  • Maps packages need to be mapped in system.config.js configuration file.
System.config({
    paths: {
        'syncfusion:': './node_modules/@syncfusion/',
    },
    map: {
        app: 'app',

        //Syncfusion packages mapping
        "@syncfusion/ej2-base": "syncfusion:ej2-base/dist/ej2-base.umd.min.js",
        "@syncfusion/ej2-buttons": "syncfusion:ej2-buttons/dist/ej2-buttons.umd.min.js",
        "@syncfusion/ej2-popups": "syncfusion:ej2-popups/dist/ej2-popups.umd.min.js",
        "@syncfusion/ej2-maps": "syncfusion:ej2-maps/dist/ej2-maps.umd.min.js"
    },
    packages: {
        'app': { main: 'app', defaultExtension: 'js' }
    }
});

The project is preconfigured with common settings (src/styles/styles.css, system.config.js ) to start with all Essential JS 2 components.

  • Tooltip CSS files are available in the ej2-maps package folder. This can be referenced in your application using the following code.

[src/styles/styles.css]

@import '../../node_modules/@syncfusion/ej2-maps/styles/material.css';

Add Map to the Project

Add the HTML div element for Map into your index.html. [src/index.html]

<!DOCTYPE html>
<html lang="en">

<head>
    <title>EJ2 Maps</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Typescript UI Controls" />
    <meta name="author" content="Syncfusion" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <script src="systemjs.config.js"></script>
</head>

<body>
     <!--container which is going to render the Map-->
     <div id='container'>
     </div>
</body>

</html>

Now import the Maps component into your app.ts to instantiate a map and append the map instance to the #container [src/app/app.ts]

import { Maps } from '@syncfusion/ej2-maps';

// initialize Maps component
let map: Maps = new Maps();

// render initialized Map
map.appendTo('#container');

Now use the npm run start command to run the application in the browser.

npm run start

The below example shows this.

import { Maps } from '@syncfusion/ej2-maps';

let map: Maps = new Maps();

map.appendTo('#element');

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 using Maps.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 using Maps.Inject method.


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.


let usMap: 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 ]] ] ] }
        }
    ]
    //..
};

Elements in the maps will get rendered in the layers. So add a layer collection to the maps by using [layers]property. Now bind the GeoJSON data to the [shapeData] property.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap } from './datasource.ts';
let map: Maps = new Maps({
   layers: [
        {
            shapeData: usMap
        }
    ]
}, '#element');

Bind data source to map

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

  • [dataSource]
  • [shapeDataPath]
  • [shapePropertyPath]

The [dataSource] 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.

The [shapeDataPath] property used to refer the data ID in dataSource. Where as, the [shapePropertyPath] 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.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap, electionData } from './datasource.ts';
let map: Maps = new Maps({
   layers: [
        {
            shapeData: usMap,
            dataSource: electionData,
            shapePropertyPath: 'name',
            shapeDataPath: 'State'
        }
    ]
}, '#element');

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 in [colorValuePath] property in [shapeSettings].

Specify color and value in [colorMapping] property. Here '#D84444' is specified for 'Trump' and '#316DB5' is specified for 'Clinton'.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap, electionData } from './datasource.ts';
let map: Maps = new Maps({
   layers: [
        {
            shapeData: usMap,
            dataSource: electionData,
            shapePropertyPath: 'name',
            shapeDataPath: 'State',
            shapeSettings: {
                colorValuePath: 'Candidate',
                colorMapping: [
                {
                    value: 'Trump', color: '#D84444'
                },
                {
                    value: 'Clinton', color: '#316DB5'
                }]
            }
        }
    ]
}, '#element');

Add Title for Maps

You can add a title using [titleSettings] property to the map to provide quick information to the user about the shapes rendered in the map.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap, electionData } from './datasource.ts';
let map: Maps = new Maps({
   layers: [
        {
            titleSettings: {
                text: 'USA Election Results - 2016'
            },
            shapeData: usMap,
            dataSource: electionData,
            shapePropertyPath: 'name',
            shapeDataPath: 'State',
            shapeSettings: {
                colorValuePath: 'Candidate',
                colorMapping: [
                {
                    value: 'Trump', color: '#D84444'
                },
                {
                    value: 'Clinton', color: '#316DB5'
                }]
            }
        }
    ]
}, '#element');

Enable Legend

You can show legend for the maps by setting true to the [visible] property in [legendSettings] object and by injecting the Legend module using Maps.Inject(Legend) method.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap, electionData } from './datasource.ts';
Maps.Inject(Legend);
let map: Maps = new Maps({
   layers: [
        {
            titleSettings: {
                text: 'USA Election Results - 2016'
            },
            shapeData: usMap,
            dataSource: electionData,
            shapePropertyPath: 'name',
            shapeDataPath: 'State',
            shapeSettings: {
                colorValuePath: 'Candidate',
                colorMapping: [
                {
                    value: 'Trump', color: '#D84444'
                },
                {
                    value: 'Clinton', color: '#316DB5'
                }]
            }
        }
    ],
    legendSettings: {
        visible: true
    }
}, '#element');

Add Data Label

You can add data labels to show additional information of the shapes in map. This can be achieved by setting [visible] property to true in the [dataLabelSettings] object and by injecting DataLabel module using Maps.Inject(DataLabel) method.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap, electionData } from './datasource.ts';
Maps.Inject(Legend, DataLabel);
let map: Maps = new Maps({
   layers: [
        {
            titleSettings: {
                text: 'USA Election Results - 2016'
            },
            shapeData: usMap,
            dataSource: electionData,
            shapePropertyPath: 'name',
            shapeDataPath: 'State',
            shapeSettings: {
                colorValuePath: 'Candidate',
                colorMapping: [
                {
                    value: 'Trump', color: '#D84444'
                },
                {
                    value: 'Clinton', color: '#316DB5'
                }]
            },
            dataLabelSettings: {
                visible: true,
                labelPath: 'State',
                smartLabelMode: 'Trim'
            }
        }
    ],
    legendSettings: {
        visible: true
    }
}, '#element');

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 the [visible] property as true in [tooltipSettings] object and by injecting MapsTooltip module using Msps.Inject(MapsTooltip) method.


import { Maps } from '@syncfusion/ej2-maps';
import { usMap, electionData } from './datasource.ts';
Maps.Inject(Legend, DataLabel);
let map: Maps = new Maps({
   layers: [
        {
            titleSettings: {
                text: 'USA Election Results - 2016'
            },
            shapeData: usMap,
            dataSource: electionData,
            shapePropertyPath: 'name',
            shapeDataPath: 'State',
            shapeSettings: {
                colorValuePath: 'Candidate',
                colorMapping: [
                {
                    value: 'Trump', color: '#D84444'
                },
                {
                    value: 'Clinton', color: '#316DB5'
                }]
            },
            dataLabelSettings: {
                visible: true,
                labelPath: 'State',
                smartLabelMode: 'Trim'
            },
            tooltipSettings: {
                visible: true,
                valuePath: 'State'
            }
        }
    ],
    legendSettings: {
        visible: true
    }
}, '#element');