HelpBot Assistant

How can I help you?

Getting started with Angular Maps component

27 Feb 202624 minutes to read

This section explains the steps required to create a map and demonstrates the basic usage of the Maps component.

Note: This guide supports Angular 21 and other recent Angular versions. For detailed compatibility with other Angular versions, please refer to the Angular version support matrix. Starting from Angular 19, standalone components are the default, and this guide reflects that architecture.

Ready to streamline your Syncfusion® Angular development? Discover the full potential of Syncfusion® Angular components with Syncfusion® AI Coding Assistant. Effortlessly integrate, configure, and enhance your projects with intelligent, context-aware code suggestions, streamlined setups, and real-time insights—all seamlessly integrated into your preferred AI-powered IDEs like VS Code, Cursor, Syncfusion® CodeStudio and more. Explore Syncfusion® AI Coding Assistant

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

Prerequisites

Ensure your development environment meets the System Requirements for Syncfusion® Angular UI Components.

Dependencies

The following is a list of the dependencies required to use the Maps component.

|-- @syncfusion/ej2-angular-maps
    |-- @syncfusion/ej2-angular-base
    |-- @syncfusion/ej2-angular-maps
    |-- @syncfusion/ej2-maps
    |-- @syncfusion/ej2-base
    |-- @syncfusion/ej2-svg-base
    |-- @syncfusion/ej2-data

Setup the Angular application

A straightforward approach to begin with Angular is to create a new application using the Angular CLI. Install Angular CLI globally with the following command:

npm install -g @angular/cli

Angular 21 Standalone Architecture: Standalone components are the default in Angular 21. This guide uses the modern standalone architecture. If you need more information about the standalone architecture, refer to the Standalone Guide.

Installing a specific version

To install a particular version of Angular CLI, use:

npm install -g @angular/[email protected]

Create a new application

With Angular CLI installed, execute this command to generate a new application:

ng new syncfusion-angular-app
  • This command will prompt you to configure settings like enabling Angular routing and choosing a stylesheet format.
? Which stylesheet format would you like to use? (Use arrow keys)
> CSS             [ https://developer.mozilla.org/docs/Web/CSS                     ]
  Sass (SCSS)     [ https://sass-lang.com/documentation/syntax#scss                ]
  Sass (Indented) [ https://sass-lang.com/documentation/syntax#the-indented-syntax ]
  Less            [ http://lesscss.org                                             ]
  • By default, a CSS-based application is created. Use SCSS if required:
ng new syncfusion-angular-app --style=scss
  • During project setup, when prompted for the Server-side rendering (SSR) option, choose the appropriate configuration.

Initial_setup

  • Select the required AI tool or ‘none’ if you do not need any AI tool.

Initial_setup

  • Navigate to your newly created application directory:
cd syncfusion-angular-app

Note: In Angular 19 and below, the CLI generates files like app.component.ts, app.component.html, app.component.css, etc. In Angular 20+, the CLI generates a simpler structure with src/app/app.ts, app.html, and app.css (no .component. suffixes).

Adding Syncfusion® Angular packages

Syncfusion®’s Angular component packages are available on npmjs.com. To use Syncfusion® Angular components, install the necessary package.

This guide uses the Angular Maps component for demonstration. Add the Angular Maps component with:

Add @syncfusion/ej2-angular-maps package to the application.

npm add @syncfusion/ej2-angular-maps --save

The above command will perform the following configurations:

  • Add the @syncfusion/ej2-angular-maps package and peer dependencies to your package.json.
  • Import the Maps component in your application.

For more details on version compatibility, refer to the Version Compatibility section.

Syncfusion® offers two package structures for Angular components:

  1. Ivy library distribution package format
  2. Angular compatibility compiler (ngcc), which is Angular’s legacy compilation pipeline.
    Syncfusion®’s latest Angular packages are provided as Ivy-compatible and suited for Angular 12 and above. To install the package, execute: 
    ng add @syncfusion/ej2-angular-maps

    For applications not compiled with Ivy, use the ngcc tagged packages:

    The ngcc packages are still compatible with Angular CLI versions 15 and below. However, they may generate warnings suggesting the use of Ivy compiled packages. Starting from Angular 16, support for the ngcc package has been completely removed. If you have further questions regarding ngcc compatibility, please refer to the following FAQ.

npm add @syncfusion/[email protected]

Add Maps component

Modify the template in the app.component.ts file to render the Maps component
[src/app/app.component.ts].

import { Component, ViewEncapsulation } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    // specifies the template string for the maps component
    template: `<ejs-maps id='maps-container'></ejs-maps>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent { }

Add the world_map GeoJSON data to the app.component.ts file.

Note: Refer to the world_map GeoJSON data at Syncfusion Downloads: https://www.syncfusion.com/downloads/support/directtrac/general/ze/world-map-2091224620. This data must be imported into src/app/app.component.ts.

import { world_map } from './world-map';

Bind the world_map data to the shapeData property of the layer in the Maps component.

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    // specifies the template string for the maps component
    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;
}

Now use the app-container in the index.html instead of the default one.

<app-container></app-container>
@Component({
    selector: 'app-container'
})

  • Now run the application in the browser using the below command.

    npm start

The example below shows a basic map.

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],
    // specifies the template string for the maps component
    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;
}

Module injection

The Maps component is divided into feature-specific modules. To use a feature, inject the corresponding service into the component’s providers array. The available service modules and their purposes are:

  • AnnotationsService - Inject this provider to use the annotations feature.
  • BubbleService - Inject this provider to use the bubble feature.
  • DataLabelService - Inject this provider to use the data label feature.
  • HighlightService - Inject this provider to use the highlight feature.
  • LegendService - Inject this provider to use the legend feature.
  • MarkerService - Inject this provider to use the marker feature.
  • MapsTooltipService - Inject this provider to use the tooltip feature.
  • NavigationLineService - Inject this provider to use the navigation lines feature.
  • SelectionService - Inject this provider to use the selection feature.
  • ZoomService - Inject this provider to use the zooming and panning feature.
  • PolygonService - Inject this provider to use the polygon feature.

This example uses the tooltip, data label, and legend features. Import the MapsTooltip, DataLabel, and Legend modules from @syncfusion/ej2-angular-maps.

In standalone components, inject the required services using the providers array in the @Component decorator:

    import { Component } from '@angular/core';
    import { LegendService, DataLabelService, MapsTooltipService, MapsModule } from '@syncfusion/ej2-angular-maps';

    @Component({
        selector: 'app-container',
        standalone: true,
        imports: [MapsModule],
        providers: [LegendService, DataLabelService, MapsTooltipService],
        template: `<ejs-maps>
            <e-layers>
                <e-layer [shapeData]='shapeData'></e-layer>
            </e-layers>
        </ejs-maps>`
    })
    export class AppComponent {
        public shapeData = world_map;
    }

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

Map elements are rendered within layers. Add a layer collection to the Maps using the layers property, then bind the GeoJSON data to the shapeData property.

import { Component, OnInit } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    template: `<ejs-maps id='rn-container'>
        <e-layers>
            <e-layer [shapeData]='shapeData'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public shapeData?: object;
    
    ngOnInit(): void {
        this.shapeData = world_map;
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Bind data source to the map

The following layer properties are used to bind a data source to the map.

  • dataSource
  • shapeDataPath
  • shapePropertyPath

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

The shapeDataPath property refers to the field in the dataSource that identifies a shape. The shapePropertyPath property refers to the field in shapeData that matches shapeDataPath. When these values match, the corresponding object from the dataSource is bound to the shape.

The JSON object containing country membership data is used as a data source below.

import { Component, OnInit } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    template: `<ejs-maps id='rn-container'>
        <e-layers>
            <e-layer [shapeData]='shapeData' [shapePropertyPath]='shapePropertyPath' [shapeDataPath]='shapeDataPath' [dataSource]='dataSource'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public dataSource?: object[];
    public shapeData?: object;
    public shapePropertyPath?: string;
    public shapeDataPath?: string;
    
    ngOnInit(): void {
        this.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" }
        ];
        this.shapeData = world_map;
        this.shapePropertyPath = 'name';
        this.shapeDataPath = 'Country';
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Apply color mapping

The color mapping feature supports customization of shape colors based on the underlying value of shapes received from bound data. Specify the field name from which the values have to be compared for the shapes in colorValuePath property in shapeSettings.

Specify the color and value in the colorMapping property. Here ‘#D84444’ is specified for ‘Permanent’ and ‘#316DB5’ is specified for ‘Non-Permanent’.

import { Component, OnInit } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    template: `<ejs-maps id='rn-container'>
        <e-layers>
            <e-layer [shapeData]='shapeData' [shapePropertyPath]='shapePropertyPath' [shapeDataPath]='shapeDataPath' [dataSource]='dataSource' [shapeSettings]='shapeSettings'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public dataSource?: object[];
    public shapeData?: object;
    public shapePropertyPath?: string;
    public shapeDataPath?: string;
    public shapeSettings?: object;
    
    ngOnInit(): void {
        this.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" }
        ];
        this.shapeData = world_map;
        this.shapePropertyPath = 'name';
        this.shapeDataPath = 'Country';
        this.shapeSettings = {
            colorValuePath: 'Membership',
            colorMapping: [
                {
                    value: 'Permanent',
                    color: '#D84444'
                },
                {
                    value: 'Non-Permanent',
                    color: '#316DB5'
                }
            ]
        };
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Add title for Maps

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

import { Component, OnInit } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    template: `<ejs-maps id='rn-container' [titleSettings]='titleSettings'>
        <e-layers>
            <e-layer [shapeData]='shapeData' [shapePropertyPath]='shapePropertyPath' [shapeDataPath]='shapeDataPath' [dataSource]='dataSource' [shapeSettings]='shapeSettings'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public titleSettings?: object;
    public dataSource?: object[];
    public shapeData?: object;
    public shapePropertyPath?: string;
    public shapeDataPath?: string;
    public shapeSettings?: object;
    
    ngOnInit(): void {
        this.titleSettings = {
            text: 'World map membership',
            titleStyle: {
                size: '16px'
            }
        };
        this.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" }
        ];
        this.shapeData = world_map;
        this.shapePropertyPath = 'name';
        this.shapeDataPath = 'Country';
        this.shapeSettings = {
            colorValuePath: 'Membership',
            colorMapping: [
                {
                    value: 'Permanent',
                    color: '#D84444'
                },
                {
                    value: 'Non-Permanent',
                    color: '#316DB5'
                }
            ]
        };
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Enable legend

You can show the legend for the map by setting the visible property to true in the legendSettings object and by injecting the LegendService in the component’s providers array.

import { Component, OnInit } from '@angular/core';
import { MapsModule, LegendService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    providers: [LegendService],
    template: `<ejs-maps id='rn-container' [legendSettings]='legendSettings'>
        <e-layers>
            <e-layer [shapeData]='shapeData' [shapePropertyPath]='shapePropertyPath' [shapeDataPath]='shapeDataPath' [dataSource]='dataSource' [shapeSettings]='shapeSettings'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public dataSource?: object[];
    public shapeData?: object;
    public shapePropertyPath?: string;
    public shapeDataPath?: string;
    public shapeSettings?: object;
    public legendSettings?: object;
    
    ngOnInit(): void {
        this.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" }
        ];
        this.shapeData = world_map;
        this.shapePropertyPath = 'name';
        this.shapeDataPath = 'Country';
        this.shapeSettings = {
            colorValuePath: 'Membership',
            colorMapping: [
                {
                    value: 'Permanent',
                    color: '#D84444'
                },
                {
                    value: 'Non-Permanent',
                    color: '#316DB5'
                }
            ]
        };
        this.legendSettings = {
            visible: true
        };
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Add data label

You can add data labels to show additional information of the shapes in the map. This can be achieved by setting the visible property to true in the dataLabelSettings object and by injecting the DataLabelService in the component’s providers array.

import { Component, OnInit } from '@angular/core';
import { MapsModule, DataLabelService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    providers: [DataLabelService],
    template: `<ejs-maps id='rn-container'>
        <e-layers>
            <e-layer [shapeData]='shapeData' [shapeSettings]='shapeSettings' [dataLabelSettings]='dataLabelSettings'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public shapeData?: object;
    public shapeSettings?: object;
    public dataLabelSettings?: object;
    
    ngOnInit(): void {
        this.shapeData = world_map;
        this.shapeSettings = {
            autofill: true
        };
        this.dataLabelSettings = {
            visible: true,
            labelPath: 'name',
            smartLabelMode: 'Trim'
        };
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Enable tooltip

The tooltip is useful when you cannot display information by using the data labels due to space constraints. You can enable the tooltip by setting the visible property to true in the tooltipSettings object and by injecting the MapsTooltipService in the component’s providers array.

import { Component, OnInit } from '@angular/core';
import { MapsModule, MapsTooltipService, DataLabelService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
    selector: 'app-container',
    standalone: true,
    imports: [MapsModule],
    providers: [MapsTooltipService, DataLabelService],
    template: `<ejs-maps id='rn-container'>
        <e-layers>
            <e-layer [shapeData]='shapeData' [shapeSettings]='shapeSettings' [dataLabelSettings]='dataLabelSettings' [tooltipSettings]='tooltipSettings'></e-layer>
        </e-layers>
    </ejs-maps>`
})
export class AppComponent implements OnInit {
    public shapeData?: object;
    public shapeSettings?: object;
    public tooltipSettings?: object;
    public dataLabelSettings?: object;
    
    ngOnInit(): void {
        this.shapeData = world_map;
        this.shapeSettings = {
            autofill: true
        };
        this.dataLabelSettings = {
            visible: true,
            labelPath: 'name',
            smartLabelMode: 'Trim'
        };
        this.tooltipSettings = {
            visible: true,
            valuePath: 'name'
        };
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));