Implementing Syncfusion React Maps

A comprehensive skill for implementing the Syncfusion React Maps component to visualize geographical data with rich interactivity, multiple layers, markers, bubbles, legends, and map provider integration.

When to Use This Skill

Use this skill when you need to:

Display geographical data on interactive maps
Visualize location-based information with markers, bubbles, or data labels
Create choropleth maps with color-coded regions based on data values
Integrate map providers like Bing Maps, OpenStreetMap, or Azure Maps
Render custom shapes from GeoJSON data files
Build multi-layer maps with overlays and sublayers
Add navigation lines to show routes or connections between locations
Implement zooming and panning for map exploration
Display statistical data on geographical regions
Create interactive legends for data interpretation
Support multiple projections (Mercator, Miller, Eckert, etc.)
Handle user interactions like tooltips, selection, and highlighting

Component Overview

The Syncfusion React Maps component is a powerful data visualization tool that renders geographical data using Scalable Vector Graphics (SVG). It supports:

Any number of layers and sublayers for complex visualizations
GeoJSON data binding for custom shape rendering
Map providers (Bing, OpenStreetMap, Azure) as base layers
6 types of projections for different map representations
Visual elements: Markers, Bubbles, Navigation Lines, Annotations, Data Labels, Legends
Interactive features: Zooming, Panning, Tooltips, Selection, Highlighting
Accessibility: WCAG 2.1 compliant with keyboard navigation
Globalization: RTL support, internationalization, localization

Key Capabilities

Data Visualization Elements

Markers: Pin locations with custom shapes, templates, and clustering
Bubbles: Display data magnitude with size-based bubbles
Data Labels: Show information directly on map shapes
Color Mapping: Apply colors based on data values (equal, range, desaturation)
Navigation Lines: Draw connections between locations with curves and arrows
Legends: Provide visual keys for data interpretation

Layer Architecture

Main Layer: Base map from GeoJSON or map provider
Sublayers: Overlay additional shapes on top of main layer
Multi-layer Support: Stack multiple layers for rich visualizations

Map Providers

Bing Maps: Satellite, aerial, and road views
OpenStreetMap: Free tile layer provider
Azure Maps: Microsoft's map service
Hybrid Approach: Combine GeoJSON shapes with provider tiles

User Interactions

Zooming: Mouse wheel, double-click, pinch, toolbar controls
Panning: Drag to explore different regions
Tooltips: Show data on hover
Selection: Highlight shapes on click
Reset: Return to initial view

Documentation and Navigation Guide

API Reference

📄 Read: references/api-reference.md

Complete MapsComponent properties reference
All available methods with examples
Comprehensive events documentation
Layer, marker, bubble, and data label settings
Legend, zoom, and tooltip configuration
Quick reference code examples
Type definitions and parameters

Getting Started

📄 Read: references/getting-started.md

Installation and package dependencies
Basic Maps component implementation
GeoJSON data structure and binding
CSS theme imports
Module injection pattern (feature-based)
First world map example
Data source binding with shapeDataPath and shapePropertyPath

Layers and Structure

📄 Read: references/layers-and-sublayers.md

Understanding layer architecture
Main layer vs sublayer differences
Creating multi-layer maps
Layer types and stacking order
Layer-specific settings and configuration
When to use multiple layers

Markers

📄 Read: references/markers.md

Adding markers to pinpoint locations
Marker data source structure (latitude, longitude)
Marker shapes and custom templates
Marker clustering for dense data
Dynamic marker updates
Interactive markers with click events
Marker tooltips and labels

Data Visualization Elements

📄 Read: references/data-visualization.md

Bubble visualization for data magnitude
Configuring bubble size and colors
Data label setup and formatting
Smart label modes (trim, hide, none)
Label templates for custom content
Combining bubbles with data labels
Best practices for visual hierarchy

Legend

📄 Read: references/legend.md

Enabling and configuring legends
Positioning strategies (absolute, dock)
Legend alignment options (near, center, far)
Interactive legends
Legend modes (default, interactive)
Customizing legend appearance
Syncing legends with color mapping

Color Mapping

📄 Read: references/color-mapping.md

Color mapping types (equal, range, desaturation)
Applying colors based on data values
Setting up colorValuePath
Creating choropleth maps
Multiple color mapping rules
Custom color schemes
Visual data representation strategies

Navigation Lines

📄 Read: references/navigation-lines.md

Creating lines between locations
Line styling (width, color, dash array)
Curved lines and angles
Arrow indicators for direction
Use cases (routes, connections, flows)
Animation effects on lines

Map Providers

📄 Read: references/map-providers.md

Overview of supported providers
When to use GeoJSON vs map providers
Bing Maps setup and API keys
OpenStreetMap integration (free)
Azure Maps configuration
Tile layer types (satellite, aerial, road)
Hybrid approaches (GeoJSON overlays on provider tiles)

User Interactions

📄 Read: references/user-interactions.md

Enabling and configuring zooming
Zoom factor and toolbar controls
Panning functionality
Tooltip configuration and templates
Selection and highlighting shapes
Mouse wheel and double-click zoom
Pinch zoom for touch devices
Reset to initial view

Annotations and Polygons

📄 Read: references/annotations-polygon.md

Adding custom annotations to maps
Polygon rendering for custom shapes
Positioning and alignment
Interactive annotations
Use cases for overlays

Customization

Map projections (Mercator, Miller, Eckert, Winkel Tripel, Aitoff, Equirectangular)
Title and subtitle configuration
Border and background styling
Margin and padding adjustments
Custom CSS classes
Theme integration
Responsive design patterns

Advanced Features

📄 Read: references/advanced-features.md

Internationalization (i18n)
Localization (l10n)
Accessibility (WCAG compliance, keyboard navigation)
State persistence across sessions
Printing and export functionality
Event handling patterns
Accessing component methods via ref
Performance optimization techniques
Migration guide from EJ1 to EJ2

Quick Start Example

tsx

import * as React from 'react';
import { MapsComponent, LayersDirective, LayerDirective, Inject, Legend } from '@syncfusion/ej2-react-maps';
import { world_map } from './world-map'; // GeoJSON data
import '@syncfusion/ej2-react-maps/styles/material.css';

function MapExample() {
  const data = [
    { Country: 'United States', Population: 331000000, Membership: 'Permanent' },
    { Country: 'Russia', Population: 145900000, Membership: 'Permanent' },
    { Country: 'China', Population: 1439000000, Membership: 'Permanent' },
    { Country: 'India', Population: 1380000000, Membership: 'Non-Permanent' },
    { Country: 'Brazil', Population: 212500000, Membership: 'Non-Permanent' }
  ];

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

export default MapExample;

Module Injection Guide

Maps features are modular. Inject only the modules you need:

tsx

import { 
  MapsComponent, 
  Inject,
  Legend,        // For legends
  DataLabel,     // For data labels
  Marker,        // For markers
  Bubble,        // For bubbles
  MapsTooltip,   // For tooltips
  Zoom,          // For zooming and panning
  Highlight,     // For highlighting shapes
  Selection,     // For selecting shapes
  NavigationLine,// For navigation lines
  Annotations,   // For annotations
  Polygon        // For polygons
} from '@syncfusion/ej2-react-maps';

<MapsComponent>
  <Inject services={[Legend, Marker, MapsTooltip, Zoom]} />
  {/* Your layers */}
</MapsComponent>

Only inject modules for features you're using to minimize bundle size.

Common Use Cases

Choropleth Map (Color-Coded Regions)

Goal: Display statistical data with color-coded countries/regions

Approach:

Bind data source with

dataSource

shapeDataPath

shapePropertyPath

Configure
```
shapeSettings.colorValuePath
```
to specify data field
Set up
```
colorMapping
```
with value-color pairs
Add
```
Legend
```
for interpretation

Example: Population density map, election results, COVID-19 statistics

Location Markers Map

Goal: Show specific locations with custom markers

Approach:

Add
```
MarkersDirective
```
inside
```
LayerDirective
```
Provide marker data with latitude/longitude
Customize marker shapes, sizes, and templates
Add tooltips for marker information

Example: Store locator, branch offices, tourist attractions

Multi-Layer Overlay

Goal: Highlight specific regions on a base map

Approach:

First layer: Base map (e.g., entire country)
Additional layers with
```
type="SubLayer"
```
: Highlighted regions
Style sublayers distinctly (different colors, borders)
Control layer visibility and order

Example: State highlights on country map, sales regions

Route Visualization

Goal: Show connections or routes between locations

Approach:

Add markers for start/end points
Use
```
NavigationLineDirective
```
to draw lines
Configure line curves, arrows, and styling
Optionally animate lines

Example: Flight routes, shipping lanes, migration patterns

Map Provider Integration

Goal: Use real-world satellite/street map as base

Approach:

Configure layer with
```
urlTemplate
```
for provider
Set up API keys (Bing, Azure) if required
Overlay GeoJSON shapes as sublayers if needed
Add markers and labels on top

Example: Real estate map, delivery tracking, ride-sharing app

Decision Trees

Should I Use GeoJSON or Map Provider?

Use GeoJSON when:

You need custom shapes or boundaries
Data is region/country-based (choropleth maps)
No real-world street-level detail needed
Offline capability required
Full control over styling and data binding

Use Map Provider when:

Need real-world satellite/aerial imagery
Street-level detail required
Real-time map updates desired
Users expect familiar map interface (like Google Maps)

Use Both (Hybrid) when:

Need real-world base with custom shape overlays
Combining statistical regions with street context

Which Color Mapping Type?

Equal Color Mapping:

Use when data has discrete categories (e.g., Membership: Permanent/Non-Permanent)
Each unique value gets a specific color

Range Color Mapping:

Use when data is numeric and continuous (e.g., Population: 0-1M, 1M-10M, 10M+)
Values within ranges get assigned colors

Desaturation Color Mapping:

Use for gradient effects based on numeric values
Single color with varying saturation levels

How Many Layers Should I Use?

Single Layer:

Simple visualizations with one data dimension
Basic country/region maps
When all data fits one layer

Multiple Layers:

Highlighting specific regions on base map
Combining different data sources
Creating visual depth with overlays
Showing borders, rivers, cities separately

Key Props Reference

MapsComponent

```
titleSettings
```
: Configure title and subtitle
```
legendSettings
```
: Legend visibility, position, alignment
```
zoomSettings
```
: Enable zooming, set initial zoom factor
```
layers
```
: Array of layer configurations

LayerDirective

```
shapeData
```
: GeoJSON data for shapes
```
dataSource
```
: Data to bind to shapes
```
shapeDataPath
```
: Field in dataSource matching shapes
```
shapePropertyPath
```
: Field in GeoJSON matching dataSource
```
shapeSettings
```
: Fill, border, color mapping
```
type
```
: "Layer" (main) or "SubLayer" (overlay)
```
markerSettings
```
: Marker configurations
```
bubbleSettings
```
: Bubble visualizations
```
dataLabelSettings
```
: Label configurations
```
tooltipSettings
```
: Tooltip customization
```
navigationLineSettings
```
: Line visualizations

Common Patterns

Module Injection: Only inject needed services to reduce bundle size
Data Binding: Use shapeDataPath + shapePropertyPath for automatic matching
Progressive Enhancement: Start with basic map, add features incrementally
Responsive Design: Maps auto-resize, but test on different viewports

Troubleshooting Quick Checks

❌ Map not displaying:

Verify GeoJSON data is correctly imported
Check console for errors
Ensure CSS is imported

❌ Colors not applied:

Confirm
```
shapeDataPath
```
matches data field name
Verify
```
shapePropertyPath
```
matches GeoJSON property
Check
```
colorValuePath
```
points to correct data field

❌ Markers not showing:

Inject
```
Marker
```
service
Set
```
visible={true}
```
in MarkerDirective
Verify latitude/longitude values are valid

❌ Zoom not working:

Inject
```
Zoom
```
service
Set
```
zoomSettings.enable={true}
```
Check if
```
enablePanning
```
is needed

❌ Legend not appearing:

Inject
```
Legend
```
service
Set
```
legendSettings.visible={true}
```
Ensure color mapping is configured

Next Steps

Start Simple: Begin with getting-started.md for basic map
Add Data: Follow data-visualization.md for markers/bubbles
Style It: Use color-mapping.md for choropleth effects
Make Interactive: Implement user-interactions.md for zoom/pan
Enhance: Add advanced features as needed

Choose the reference documentation that matches your current implementation phase and specific requirements.

syncfusion-react-maps

NPX Install

Tags

SKILL.md Content

Implementing Syncfusion React Maps

When to Use This Skill

Component Overview

Key Capabilities

Data Visualization Elements

Layer Architecture

Map Providers

User Interactions

Documentation and Navigation Guide

API Reference

Getting Started

Layers and Structure

Markers

Data Visualization Elements

Legend

Color Mapping

Navigation Lines

Map Providers

User Interactions

Annotations and Polygons

Customization

Advanced Features

Quick Start Example

Module Injection Guide

Common Use Cases

Choropleth Map (Color-Coded Regions)

Location Markers Map

Multi-Layer Overlay

Route Visualization

Map Provider Integration

Decision Trees

Should I Use GeoJSON or Map Provider?

Which Color Mapping Type?

How Many Layers Should I Use?

Key Props Reference

MapsComponent

LayerDirective

Common Patterns

Troubleshooting Quick Checks

Next Steps