Syncfusion Flutter Maps

This skill covers the Syncfusion Flutter Maps (SfMaps) widget for displaying and visualizing geographical and spatial data. The widget supports two primary layer types: MapShapeLayer (for GeoJSON-based shape rendering) and MapTileLayer (for web map tile services like OpenStreetMap and Bing Maps).

When to Use This Skill

Use this skill when you need to:

Display interactive maps with zoom, pan, and selection capabilities
Visualize geographical data using shapes, colors, and bubbles
Render GeoJSON data as maps (countries, states, regions, custom shapes)
Integrate tile-based maps from OpenStreetMap, Bing Maps, Google Maps, or TomTom
Add markers to maps for locations, points of interest, or custom coordinates
Create choropleth maps with color-coded regions based on data values
Build bubble maps showing data through size and color variations
Display data labels and legends for map interpretation
Implement tooltips for shapes, bubbles, and markers
Enable map interactions including selection, zoom, pan, and navigation
Add vector layers (arcs, circles, lines, polygons, polylines) for custom overlays
Visualize spatial relationships with sublayers and hierarchical data
Create location-based applications with coordinate mapping

Component Overview

The SfMaps widget is a comprehensive mapping solution for Flutter that supports two primary layer types:

MapShapeLayer - GeoJSON-based shape rendering for statistical and geographical data visualization. Features include choropleth maps with color/range mapping, bubble visualizations, data labels, shape selection, legends, tooltips, sublayers for hierarchical data, vector layers (arcs, circles, lines, polygons, polylines), markers, zoom and pan gestures, and offline support. Ideal for election maps, sales territories, census data, and region-based analytics.

MapTileLayer - Web map tile service integration for OpenStreetMap, Bing Maps, Google Maps, and TomTom. Features include real-world street maps with detailed geography, markers for location pins, sublayers, vector layers, zoom and pan with configurable levels, initial focal point and zoom, and WMTS URL templates. Requires internet connectivity. Perfect for store locators, delivery tracking, and navigation apps.

Both layer types support markers (built-in symbols and custom widgets), zoom/pan behavior with pinch/mouse wheel/double-tap gestures, vector layer overlays, accessibility features, RTL support, and theming through

SfMapsTheme

Choosing the Right Layer Type

Use MapShapeLayer when:

You have GeoJSON data defining geographical shapes
You need choropleth maps (color-coded by region/country)
Your data is statistical and tied to geographical boundaries
You want complete control over shape appearance and data binding
You need offline maps that don't require external tile services
Custom shapes or specific regions need to be highlighted
Building: election maps, sales territory maps, census data visualizations, region comparisons

Use MapTileLayer when:

You need real-world street maps from providers like OpenStreetMap
Your app requires detailed geographical features (roads, landmarks, terrain)
Online connectivity is available for tile loading
You want standard map views without custom data rendering
Street-level detail or satellite imagery is needed
You need to show precise locations on familiar map backgrounds
Building: store locators, delivery tracking, navigation apps, location pickers

Key Differences Summary:

Feature	MapShapeLayer	MapTileLayer
Data Source	GeoJSON files	Web tile services (URLs)
Offline Support	✅ Yes (embedded GeoJSON)	❌ Requires internet
Data Binding	✅ Full support	❌ Limited to markers
Choropleth Maps	✅ Yes	❌ No
Bubble Visualization	✅ Yes	❌ No
Data Labels	✅ Yes	❌ No
Shape Selection	✅ Yes	❌ No
Color Mapping	✅ Yes	❌ No
Legend	✅ Yes	❌ No
Markers	✅ Yes	✅ Yes
Zoom & Pan	✅ Yes	✅ Yes
Street Maps	❌ No	✅ Yes
Sublayers	✅ Yes	✅ Yes
Vector Layers	✅ Yes (arc, circle, line, etc.)	✅ Yes (arc, circle, line, etc.)
Tooltips	✅ Yes (shapes & bubbles)	❌ Limited
Real-world Detail	❌ Limited	✅ High detail

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Installation and package setup
Basic MapShapeLayer implementation
Basic MapTileLayer implementation
Loading GeoJSON data (asset, network, memory)
OpenStreetMap quick start
Package dependencies and imports

Layer Overview

📄 For Shape Layer: references/shape-layer.md

MapShapeLayer widget overview and features
GeoJSON data source configuration
Shape data field mapping
Shape appearance (color, stroke)
Loading progress indicator
When to use Shape Layer
Basic shape rendering

📄 For Tile Layer: references/tile-layer.md

MapTileLayer widget overview and features
URL template format (WMTS)
OpenStreetMap integration
Bing Maps setup and API keys
Other providers (TomTom, MapBox, Google Maps)
Initial focal point configuration
Initial zoom level setup

Markers

📄 Read: references/markers.md

Adding markers to both layer types
Built-in marker symbols (circle, diamond, triangle, etc.)
Custom marker widgets
Marker positioning (latitude/longitude)
Marker appearance customization
Dynamic marker management (add/update/remove)
Marker controllers (MapShapeLayerController/MapTileLayerController)
Marker alignment and offset
Zoom markers to fit bounds

Data Visualization Features (Shape Layer)

📄 Read: references/data-labels.md

Showing data labels on shapes
Data label mapper configuration
Label text customization
Label trimming and overflow handling
Label styling and positioning

📄 Read: references/legend.md

Legend configuration and positioning
Legend for shape colors
Legend for bubbles
Legend customization (icons, text, layout)
Legend toggling feature
Legend interactions

📄 Read: references/tooltip.md

Shape tooltips with builders
Bubble tooltips
Marker tooltips
Tooltip customization
Tooltip styling and positioning
Tooltip settings (color, stroke, padding)

📄 Read: references/bubble.md

Bubble visualization overview
Bubble size mapping based on data
Bubble color mapping
Bubble appearance customization
Bubble tooltips
Use cases for bubble maps

Color and Data Mapping

📄 Read: references/color-mapping.md

Equal color mapping (discrete values)
Range color mapping (continuous ranges)
Shape color value mapper
Bubble color value mapper
Color mappers configuration
Opacity settings (min/max)
Returning colors directly vs using mappers
Color mapping patterns

Selection and Interaction

📄 Read: references/selection.md

Shape selection feature
Selection callbacks
Selection styling and decoration
Single vs multi-selection
Programmatic selection
Toggling selection

📄 Read: references/zoom-pan.md

MapZoomPanBehavior configuration
Pinch zoom (mobile)
Mouse wheel zoom (desktop)
Zoom toolbar (web platform)
Double-tap zoom
Zoom level configuration
Pan behavior and restrictions
Focal latitude/longitude bounds
Zoom callbacks and events

Advanced Features

📄 Read: references/vector-layers.md

MapArcLayer (arcs between two coordinates)
MapCircleLayer (circles at specific coordinates)
MapLineLayer (lines connecting coordinates)
MapPolygonLayer (polygon shapes)
MapPolylineLayer (connected line segments)
Vector layer styling and customization
Use cases for each vector type

📄 Read: references/shape-sublayer.md

Adding sublayers to MapShapeLayer
Sublayer configuration and nesting
Sublayer markers and bubbles
Hierarchical data visualization
Use cases for sublayers

Customization and Theming

📄 Read: references/customization.md

SfMapsTheme integration
Visual appearance customization
Shape styling (colors, borders)
Hover effects (web platform)
Theme integration
Responsive design patterns
Custom map styling

📄 Read: references/accessibility.md

Screen reader support
Semantic labels for shapes
Keyboard navigation
WCAG compliance
Focus indicators
Accessible map interactions

Quick Start Examples

Basic Shape Layer with GeoJSON

dart

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_maps/maps.dart';

class MyShapeMap extends StatefulWidget {
  @override
  _MyShapeMapState createState() => _MyShapeMapState();
}

class _MyShapeMapState extends State<MyShapeMap> {
  late MapShapeSource _dataSource;
  
  @override
  void initState() {
    super.initState();
    _dataSource = MapShapeSource.asset(
      'assets/world_map.json',
      shapeDataField: 'name',
    );
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('World Map')),
      body: Padding(
        padding: EdgeInsets.all(15),
        child: SfMaps(
          layers: [
            MapShapeLayer(
              source: _dataSource,
              color: Colors.blue[100],
              strokeColor: Colors.blue,
              strokeWidth: 0.5,
            ),
          ],
        ),
      ),
    );
  }
}

Basic Tile Layer with OpenStreetMap

dart

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_maps/maps.dart';

class MyTileMap extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('OpenStreetMap')),
      body: SfMaps(
        layers: [
          MapTileLayer(
            urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
            initialFocalLatLng: MapLatLng(27.1751, 78.0421),
            initialZoomLevel: 5,
          ),
        ],
      ),
    );
  }
}

Choropleth Map with Color Mapping

dart

class ChoroplethMap extends StatefulWidget {
  @override
  _ChoroplethMapState createState() => _ChoroplethMapState();
}

class _ChoroplethMapState extends State<ChoroplethMap> {
  late List<Model> _data;
  late MapShapeSource _dataSource;
  
  @override
  void initState() {
    super.initState();
    _data = [
      Model('India', 280),
      Model('United States of America', 190),
      Model('Brazil', 120),
    ];
    
    _dataSource = MapShapeSource.asset(
      'assets/world_map.json',
      shapeDataField: 'name',
      dataCount: _data.length,
      primaryValueMapper: (int index) => _data[index].country,
      shapeColorValueMapper: (int index) => _data[index].value,
      shapeColorMappers: [
        MapColorMapper(from: 0, to: 100, color: Colors.red),
        MapColorMapper(from: 101, to: 300, color: Colors.green),
      ],
    );
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SfMaps(
        layers: [
          MapShapeLayer(
            source: _dataSource,
            legend: MapLegend(MapElement.shape),
            showDataLabels: true,
          ),
        ],
      ),
    );
  }
}

class Model {
  Model(this.country, this.value);
  final String country;
  final double value;
}

Map with Markers

dart

class MapWithMarkers extends StatefulWidget {
  @override
  _MapWithMarkersState createState() => _MapWithMarkersState();
}

class _MapWithMarkersState extends State<MapWithMarkers> {
  late List<MarkerData> _markers;
  late MapShapeSource _dataSource;
  
  @override
  void initState() {
    super.initState();
    _markers = [
      MarkerData('New York', 40.7128, -74.0060),
      MarkerData('London', 51.5074, -0.1278),
      MarkerData('Tokyo', 35.6762, 139.6503),
    ];
    
    _dataSource = MapShapeSource.asset(
      'assets/world_map.json',
      shapeDataField: 'name',
    );
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SfMaps(
        layers: [
          MapShapeLayer(
            source: _dataSource,
            initialMarkersCount: _markers.length,
            markerBuilder: (BuildContext context, int index) {
              return MapMarker(
                latitude: _markers[index].latitude,
                longitude: _markers[index].longitude,
                iconColor: Colors.red,
                iconType: MapIconType.circle,
                size: Size(15, 15),
                child: null,
              );
            },
          ),
        ],
      ),
    );
  }
}

class MarkerData {
  MarkerData(this.city, this.latitude, this.longitude);
  final String city;
  final double latitude;
  final double longitude;
}

Common Patterns

Pattern 1: Interactive Choropleth Map with Selection

dart

// Common pattern for election results, sales data by region, etc.
late MapShapeSource _dataSource;
int? _selectedIndex;

_dataSource = MapShapeSource.asset(
  'assets/usa_states.json',
  shapeDataField: 'name',
  dataCount: _statesData.length,
  primaryValueMapper: (index) => _statesData[index].state,
  shapeColorValueMapper: (index) => _statesData[index].value,
  shapeColorMappers: [
    MapColorMapper(from: 0, to: 50, color: Colors.red),
    MapColorMapper(from: 51, to: 100, color: Colors.blue),
  ],
);

MapShapeLayer(
  source: _dataSource,
  legend: MapLegend(MapElement.shape),
  showDataLabels: true,
  onSelectionChanged: (int index) {
    setState(() {
      _selectedIndex = index;
    });
  },
  selectionSettings: MapSelectionSettings(
    color: Colors.yellow,
    strokeColor: Colors.black,
    strokeWidth: 2,
  ),
)

Pattern 2: Tile Layer with Custom Markers

dart

// Common pattern for store locator, delivery tracking
late List<LocationData> _locations;
late MapTileLayerController _controller;

@override
void initState() {
  _controller = MapTileLayerController();
  _locations = [/* your location data */];
  super.initState();
}

MapTileLayer(
  urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
  initialFocalLatLng: MapLatLng(37.7749, -122.4194),
  initialZoomLevel: 10,
  controller: _controller,
  initialMarkersCount: _locations.length,
  markerBuilder: (context, index) {
    return MapMarker(
      latitude: _locations[index].latitude,
      longitude: _locations[index].longitude,
      child: Icon(Icons.location_pin, color: Colors.red, size: 30),
    );
  },
  zoomPanBehavior: MapZoomPanBehavior(
    enableDoubleTapZooming: true,
    enablePinching: true,
    enablePanning: true,
  ),
)

Pattern 3: Map with Bubbles and Tooltips

dart

// Common pattern for population density, sales volume visualization
_dataSource = MapShapeSource.asset(
  'assets/world_map.json',
  shapeDataField: 'name',
  dataCount: _data.length,
  primaryValueMapper: (index) => _data[index].country,
  bubbleSizeMapper: (index) => _data[index].population,
  bubbleColorValueMapper: (index) => _data[index].density,
);

MapShapeLayer(
  source: _dataSource,
  showDataLabels: true,
  legend: MapLegend.bar(MapElement.bubble),
  bubbleSettings: MapBubbleSettings(
    maxRadius: 50,
    minRadius: 10,
    color: Colors.blue,
  ),
  shapeTooltipBuilder: (context, index) {
    return Padding(
      padding: EdgeInsets.all(8),
      child: Text(
        '${_data[index].country}: ${_data[index].population}M',
        style: TextStyle(color: Colors.white),
      ),
    );
  },
  bubbleTooltipBuilder: (context, index) {
    return Padding(
      padding: EdgeInsets.all(8),
      child: Text(
        'Density: ${_data[index].density}/km²',
        style: TextStyle(color: Colors.white),
      ),
    );
  },
)

Pattern 4: Zoom to Fit Markers

dart

// Show specific region with markers
late MapZoomPanBehavior _zoomPanBehavior;

@override
void initState() {
  _zoomPanBehavior = MapZoomPanBehavior(
    enableDoubleTapZooming: true,
    enablePinching: true,
    enablePanning: true,
  );
  super.initState();
}

// Button to fit bounds
void _fitToMarkers() {
  setState(() {
    // Define bounds to show all markers
    _zoomPanBehavior.latLngBounds = MapLatLngBounds(
      MapLatLng(southwestLat, southwestLng),
      MapLatLng(northeastLat, northeastLng),
    );
  });
}

MapShapeLayer(
  source: _dataSource,
  zoomPanBehavior: _zoomPanBehavior,
  // ... markers
)

Pattern 5: Dynamic Marker Addition (Tap to Add)

dart

// Add markers where user taps
late MapLatLng _markerPosition;
late MapShapeLayerController _controller;
late CustomZoomPanBehavior _zoomPanBehavior;

@override
void initState() {
  _controller = MapShapeLayerController();
  _zoomPanBehavior = CustomZoomPanBehavior()
    ..onTap = _handleTap;
  super.initState();
}

void _handleTap(Offset position) {
  _markerPosition = _controller.pixelToLatLng(position);
  if (_controller.markersCount > 0) {
    _controller.clearMarkers();
  }
  _controller.insertMarker(0);
}

MapShapeLayer(
  source: _dataSource,
  controller: _controller,
  zoomPanBehavior: _zoomPanBehavior,
  markerBuilder: (context, index) {
    return MapMarker(
      latitude: _markerPosition.latitude,
      longitude: _markerPosition.longitude,
      child: Icon(Icons.location_on, color: Colors.red),
    );
  },
)

class CustomZoomPanBehavior extends MapZoomPanBehavior {
  late Function(Offset) onTap;
  
  @override
  void handleEvent(PointerEvent event) {
    if (event is PointerUpEvent) {
      onTap(event.localPosition);
    }
    super.handleEvent(event);
  }
}

Key Properties

MapShapeLayer Essential Properties

```
source
```
- MapShapeSource with GeoJSON data and mappings
```
color
```
- Default color for all shapes
```
strokeColor
```
- Border color for shapes
```
strokeWidth
```
- Border width for shapes
```
legend
```
- Legend configuration (bar or default)
```
showDataLabels
```
- Show labels on shapes
```
initialMarkersCount
```
- Number of markers to display
```
markerBuilder
```
- Builder function for markers
```
controller
```
- MapShapeLayerController for dynamic updates
```
zoomPanBehavior
```
- Zoom and pan configuration
```
onSelectionChanged
```
- Callback when shape is selected
```
selectionSettings
```
- Selection appearance settings
```
shapeTooltipBuilder
```
- Custom tooltip for shapes
```
bubbleTooltipBuilder
```
- Custom tooltip for bubbles
```
markerTooltipBuilder
```
- Custom tooltip for markers
```
tooltipSettings
```
- Tooltip styling configuration
```
bubbleSettings
```
- Bubble appearance settings
```
dataLabelSettings
```
- Data label styling
```
legendSettings
```
- Legend appearance settings
```
sublayers
```
- List of MapSublayer widgets
```
loadingBuilder
```
- Widget shown while loading GeoJSON

MapTileLayer Essential Properties

```
urlTemplate
```
- Tile provider URL in WMTS format
```
initialFocalLatLng
```
- Initial center point (latitude, longitude)
```
initialZoomLevel
```
- Initial zoom level (1-15+)
```
initialMarkersCount
```
- Number of markers to display
```
markerBuilder
```
- Builder function for markers
```
controller
```
- MapTileLayerController for dynamic updates
```
zoomPanBehavior
```
- Zoom and pan configuration
```
markerTooltipBuilder
```
- Custom tooltip for markers
```
initialLatLngBounds
```
- Bounds to fit on load

MapShapeSource Essential Properties

```
shapeDataField
```
- Field name in GeoJSON to match with data
```
dataCount
```
- Number of data items
```
primaryValueMapper
```
- Maps data index to shape identifier
```
dataLabelMapper
```
- Maps data index to label text
```
shapeColorValueMapper
```
- Maps data index to color value
```
shapeColorMappers
```
- Color mappers for equal/range mapping
```
bubbleSizeMapper
```
- Maps data index to bubble size
```
bubbleColorValueMapper
```
- Maps data index to bubble color
```
bubbleColorMappers
```
- Color mappers for bubbles

MapZoomPanBehavior Essential Properties

```
enableDoubleTapZooming
```
- Enable double-tap to zoom
```
enablePinching
```
- Enable pinch zoom (mobile)
```
enablePanning
```
- Enable pan gesture
```
enableMouseWheelZooming
```
- Enable mouse wheel zoom
```
showToolbar
```
- Show zoom toolbar (web)
```
toolbarSettings
```
- Toolbar appearance
```
zoomLevel
```
- Current zoom level (read/write)
```
focalLatLng
```
- Current center point (read/write)
```
latLngBounds
```
- Bounds to fit dynamically
```
minZoomLevel
```
- Minimum zoom level
```
maxZoomLevel
```
- Maximum zoom level
```
onZooming
```
- Callback during zoom
```
onPanning
```
- Callback during pan

Common Use Cases

Election Results Map - Use MapShapeLayer with color mapping by state/region
Store Locator - Use MapTileLayer with custom marker icons
Sales Territory Map - Use MapShapeLayer with bubbles showing sales volume
Population Density Map - Use MapShapeLayer with choropleth coloring
Delivery Tracking - Use MapTileLayer with real-time marker updates
Weather Map - Use MapShapeLayer with color mapping for temperature/conditions
Property Finder - Use MapTileLayer with markers and zoom-to-fit
Regional Analytics - Use MapShapeLayer with legends, tooltips, and selection
Route Planning - Use MapTileLayer with polyline vector layers
Census Data Visualization - Use MapShapeLayer with data labels and legends

syncfusion-flutter-maps

NPX Install

Tags

SKILL.md Content

Syncfusion Flutter Maps

When to Use This Skill

Component Overview

Choosing the Right Layer Type

Use MapShapeLayer when:

Use MapTileLayer when:

Key Differences Summary:

Documentation and Navigation Guide

Getting Started

Layer Overview

Markers

Data Visualization Features (Shape Layer)

Color and Data Mapping

Selection and Interaction

Advanced Features

Customization and Theming

Quick Start Examples

Basic Shape Layer with GeoJSON

Basic Tile Layer with OpenStreetMap

Choropleth Map with Color Mapping

Map with Markers

Common Patterns

Pattern 1: Interactive Choropleth Map with Selection

Pattern 2: Tile Layer with Custom Markers

Pattern 3: Map with Bubbles and Tooltips

Pattern 4: Zoom to Fit Markers

Pattern 5: Dynamic Marker Addition (Tap to Add)

Key Properties

MapShapeLayer Essential Properties

MapTileLayer Essential Properties

MapShapeSource Essential Properties

MapZoomPanBehavior Essential Properties

Common Use Cases