HelpBot Assistant

How can I help you?

Getting Started with React Maps Library 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.

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

Dependencies

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

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

Installation and Configuration

To easily set up a React application, use the Vite CLI (npm create vite), which provides a faster development environment, smaller bundle sizes, and optimized builds compared to traditional tools like create-react-app. For detailed steps, refer to the Vite installation instructions. Vite sets up your environment using JavaScript and optimizes your application for production.

Note: To create a React application using create-react-app instead, refer to this documentation for more details.

To create a new React application, run the following command.

npm create vite@latest my-app

This command will prompt you for a few settings for the new project, such as selecting a framework and a variant.

Initial_setup

To set up a React application in a TypeScript environment, run the following command.

npm create vite@latest my-app -- --template react-ts
cd my-app
npm run dev

To set up a React application in a JavaScript environment, run the following command.

npm create vite@latest my-app -- --template react
cd my-app
npm run dev

Adding Syncfusion^® packages

All the available Essential^® JS 2 packages are published in npmjs.com public registry.
To install the Syncfusion^® Maps package, use the following command.

npm install @syncfusion/ej2-react-maps --save

The –save will instruct NPM to include the Maps package inside the dependencies section of the package.json.

Add Map to the Project

Now, the Maps component can be added to the application. To initialize the Maps component in the React application, import the MapsComponent into src/App.js. If you are using TypeScript, you can import the MapsComponent into src/App.tsx. You can choose the appropriate option based on your application. In the following code, the MapsComponent is included in the src/App.js file.

Note: Before running this code, download the world_map.ts file from the link provided below and place it in your project’s src folder.

import { world_map } from './world_map.ts';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

function App() {
    return (
        <div className="App">
            <MapsComponent id="maps">
                <LayersDirective>
                    <LayerDirective shapeData={world_map}>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
        </div>
    );
}

export default App;

Note: Refer to the world_map dataset here: https://www.syncfusion.com/downloads/support/directtrac/general/ze/world_map1557035892

Run the application

Now, run the npm run dev command in the console to start the development server. This command compiles your code and serves the application locally, opening it in the browser.

npm run dev

Module Injection

The Maps component is divided into feature-specific modules. To use a feature, inject its module with the Inject method. You only need to inject the modules for features you are actually using in your application. The available modules and their purposes are:

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 feature.
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.
Polygon - Inject this provider to use polygon feature.

For example, to use the tooltip, data label, and legend features, import the corresponding modules and inject them into the Maps component using the Inject component.

import * as React from 'react';
import { MapsComponent, Inject, DataLabel, Legend, MapsTooltip } from '@syncfusion/ej2-react-maps';

export function App() {
    return (
        <MapsComponent>
            <Inject services={[DataLabel, Legend, MapsTooltip]} />
        </MapsComponent>
    );
}

const root = ReactDOM.createRoot(document.getElementById('container'));
root.render(<App />);

Render shapes from GeoJSON data

This section shows how to bind GeoJSON data to a layer. The following example demonstrates the structure of GeoJSON data:

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. While the above example shows a US map structure, the following code demonstrates rendering with world map data.

app.jsx
app.tsx
import { world_map } from '../world-map';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return (<MapsComponent id="maps">
            <LayersDirective>
                <LayerDirective shapeData={world_map}>
                </LayerDirective>
            </LayersDirective>
        </MapsComponent>);
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return (<MapsComponent id="maps">
            <LayersDirective>
                <LayerDirective shapeData={world_map}>
                </LayerDirective>
            </LayersDirective>
        </MapsComponent>);
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

Bind data source to map

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

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 in 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 “uncountries” is used as data source below.

app.jsx
app.tsx
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
   return(
            <MapsComponent >
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return(
            <MapsComponent >
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

Note: Refer to the value of the data source world-map.ts and data.ts here.

Apply Color Mapping

The Color Mapping feature supports customization of shape colors based on the underlying value of shape received from the bound 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 ‘Permanent’ and ‘#316DB5’ is specified for ‘Non-Permanent’ membership types.

app.jsx
app.tsx
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent >
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}
                        shapeSettings={ {
                            colorValuePath: 'Membership',
                            colorMapping: [
                                {
                                    value: 'Permanent', color: '#D84444'
                                },
                                {
                                    value: 'Non-Permanent', color: '#316DB5'
                                }]
                        } }>
                    </LayerDirective>
                </LayersDirective>
        </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent >
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}
                        shapeSettings={ {
                            colorValuePath: 'Membership',
                            colorMapping: [
                                {
                                    value: 'Permanent', color: '#D84444'
                                },
                                {
                                    value: 'Non-Permanent', color: '#316DB5'
                                }]
                        } }>
                    </LayerDirective>
                </LayersDirective>
        </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

Note: Refer to the value of the data source world-map.ts and data.ts here.

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.

app.jsx
app.tsx
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent   titleSettings={ { text: 'World map with membership' } }>
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}
                        shapeSettings={ {
                            colorValuePath: 'Membership',
                            colorMapping: [
                                {
                                   value: 'Permanent', color: '#D84444'
                               },
                               {
                                   value: 'Non-Permanent', color: '#316DB5'
                               }]
                        } }>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent   titleSettings={ { text: 'World map with membership' } }>
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}
                        shapeSettings={ {
                            colorValuePath: 'Membership',
                            colorMapping: [
                                {
                                   value: 'Permanent', color: '#D84444'
                               },
                               {
                                   value: 'Non-Permanent', color: '#316DB5'
                               }]
                        } }>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

Note: Refer to the value of the data source world-map.ts and data.ts here.

Enable Legend

You can show a legend for the maps by setting the visible property as true in legendSettings object and by injecting the Legend service using Inject tag.

app.jsx
app.tsx
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective, Inject, Legend } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent  legendSettings={ { visible: true } } >
            <Inject services={[Legend]} />
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}
                        shapeSettings={ {
                            colorValuePath: 'Membership',
                            colorMapping: [
                                {
                                    value: 'Permanent', color: '#D84444'
                                },
                                {
                                    value: 'Non-Permanent', color: '#316DB5'
                                }]
                        } }>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import { uncountries } from '../data';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective, Inject, Legend } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent  legendSettings={ { visible: true } } >
            <Inject services={[Legend]} />
                <LayersDirective>
                    <LayerDirective shapeData={world_map} shapeDataPath='Country' shapePropertyPath='name' dataSource={uncountries}
                        shapeSettings={ {
                            colorValuePath: 'Membership',
                            colorMapping: [
                                {
                                    value: 'Permanent', color: '#D84444'
                                },
                                {
                                    value: 'Non-Permanent', color: '#316DB5'
                                }]
                        } }>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

Note: Refer to the value of the data source world-map.ts and data.ts here.

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 DataLabel service using Inject tag.

app.jsx
app.tsx
import { world_map } from '../world-map';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective, Inject, DataLabel } from '@syncfusion/ej2-react-maps';

export function App(){
    return(<MapsComponent >
            <Inject services={[DataLabel]} />
                <LayersDirective>
                    <LayerDirective shapeData={world_map}
                    dataLabelSettings={ {
                        visible: true,
                        labelPath: 'name',
                        smartLabelMode: 'Trim'
                    } }>
                    </LayerDirective>
                </LayersDirective>
        </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective, Inject, DataLabel } from '@syncfusion/ej2-react-maps';

export function App(){
    return(<MapsComponent >
            <Inject services={[DataLabel]} />
                <LayersDirective>
                    <LayerDirective shapeData={world_map}
                    dataLabelSettings={ {
                        visible: true,
                        labelPath: 'name',
                        smartLabelMode: 'Trim'
                    } }>
                    </LayerDirective>
                </LayersDirective>
        </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

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 to true in tooltipSettings object and by injecting MapsTooltip service using Inject tag.

app.jsx
app.tsx
import { world_map } from '../world-map';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective, Inject, MapsTooltip } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent >
            <Inject services={[MapsTooltip]} />
                <LayersDirective>
                    <LayerDirective shapeData={world_map}
                     tooltipSettings={ {
                        visible: true,
                        valuePath: 'name'
                    } }>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);
import { world_map } from '../world-map';
import * as React from "react";
import { createRoot } from 'react-dom/client';
import { MapsComponent, LayersDirective, LayerDirective, Inject, MapsTooltip } from '@syncfusion/ej2-react-maps';

export function App() {
    return(<MapsComponent >
            <Inject services={[MapsTooltip]} />
                <LayersDirective>
                    <LayerDirective shapeData={world_map}
                     tooltipSettings={ {
                        visible: true,
                        valuePath: 'name'
                    } }>
                    </LayerDirective>
                </LayersDirective>
            </MapsComponent>
    );
}

const root = createRoot(document.getElementById('container'));
root.render(<App />);

NOTE

You can refer to our React Maps Library feature tour page for its groundbreaking feature representations. You can also explore our React Maps Library example that shows you how to configure the Maps Library in React.

Search docs

Ask HelpBot

Search docs

Ask HelpBot

How can I help you?

Getting Started with React Maps Library component

Dependencies

Installation and Configuration

Adding Syncfusion^® packages

Add Map to the Project

Run the application

Module Injection

Render shapes from GeoJSON data

Bind data source to map

Apply Color Mapping

Add Title for Maps

Enable Legend

Add Data Label

Enable Tooltip

How can I help you?

Getting Started with React Maps Library component

Dependencies

Installation and Configuration

Adding Syncfusion® packages

Add Map to the Project

Run the application

Module Injection

Render shapes from GeoJSON data

Bind data source to map

Apply Color Mapping

Add Title for Maps

Enable Legend

Add Data Label

Enable Tooltip

Adding Syncfusion^® packages