SfMaps class

A data visualization component that displays statistical information for a geographical area.

The SfMaps.layers is a collection of MapLayer. It contains either MapShapeLayer and MapTileLayer.

Shape layer

The MapShapeLayer has the following elements and features,

  • The "data labels", to provide information to users about the respective shape.
  • The "markers", which denotes a location with built-in symbols and allows displaying custom widgets at a specific latitude and longitude on a map.
  • The "bubbles", which adds information to shapes such as population density, number of users, and more. Bubbles can be rendered in different colors and sizes based on the data values of their assigned shape.
  • The "legend", to provide clear information on the data plotted in the map through shapes and bubbles. You can use the legend toggling feature to visualize only the shapes or bubbles which needs to be visualized.
  • The "color mapping", to categorize the shapes and bubbles on a map by customizing their color based on the underlying value. It is possible to set the shape or bubble color for a specific value or for a range of values.
  • The "tooltip", to display additional information about shapes and bubbles using the customizable tooltip on a map.
  • Along with this, the selection feature helps to highlight that area on a map on interaction. You can use the callback for performing any action during shape selection.

The actual geographical rendering is done here using the MapShapeLayer.source. The source which contains the GeoJSON data can be set as the .json file from an asset bundle, network or from Uint8List as bytes.

The MapShapeSource.shapeDataField property is used to refer the unique field name in the .json file to identify each shapes and map with the respective data in the data source.

By default, the value specified for the MapShapeSource.shapeDataField in the GeoJSON file will be used in the elements like data labels, tooltip, and legend for their respective shapes.

However, it is possible to keep a data source and customize these elements based on the requirement. The value of the MapShapeSource.shapeDataField will be used to map with the respective data returned in MapShapeSource.primaryValueMapper from the data source.

Once the above mapping is done, you can customize the elements using the APIs like MapShapeSource.dataLabelMapper, MapShapeSource.shapeColorMappers, etc.


This snippet shows how to create the SfMaps.

Widget build(BuildContext context) {
  return const SfMaps(
    layers: [
        source: MapShapeSource.asset(
            shapeDataField: "continent",

Tile layer

Tile layer which renders the tiles returned from the Web Map Tile Services (WMTS) like OpenStreetMap, Bing Maps, Google Maps, TomTom etc.

The MapTileLayer.urlTemplate accepts the URL in WMTS format i.e. {z} — zoom level, {x} and {y} — tile coordinates.

This URL might vary slightly depends on the providers. The formats can be, https://exampleprovider/{z}/{x}/{y}.png, https://exampleprovider/z={z}/x={x}/y={y}.png, https://exampleprovider/z={z}/x={x}/y={y}.png?key=subscription_key, etc.

We will replace the {z}, {x}, {y} internally based on the current center point and the zoom level.

The subscription key may be needed for some of the providers. Please include them in the MapTileLayer.urlTemplate itself as mentioned in above example. Please note that the format may vary between the each map provider. You can check the exact URL format needed for the providers in their official websites.

Regarding the tile rendering, at the lowest zoom level (Level 0), the map is 256 x 256 pixels and the whole world map renders as a single tile. At each increase in level, the map width and height grow by a factor of 2 i.e. Level 1 is 512 x 512 pixels with 4 tiles ((0, 0), (0, 1), (1, 0), (1, 1) where 0 and 1 are {x} and {y} in MapTileLayer.urlTemplate), Level 2 is 2048 x 2048 pixels with 8 tiles (from (0, 0) to (3, 3)), and so on. (These details are just for your information and all these calculation are done internally.)

However, based on the size of the SfMaps widget, MapTileLayer.initialFocalLatLng and MapTileLayer.initialZoomLevel, number of initial tiles needed in the view port alone will be rendered. While zooming and panning, new tiles will be requested and rendered on demand based on the current zoom level and focal point. The current zoom level and focal point can be obtained from the MapZoomPanBehavior.zoomLevel and MapZoomPanBehavior.focalLatLng respectively. Once the particular tile is rendered, it will be stored in the cache and it will be used from it for the next time for better performance.

Regarding the cache and clearing it, please check the APIs in imageCache.

  Widget build(BuildContext context) {
    return SfMaps(
      layers: [
          urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
          initialFocalLatLng: MapLatLng(-23.698042, 133.880753),
          initialZoomLevel: 3

See also:



SfMaps({Key? key, required List<MapLayer> layers})
Creates a SfMaps.


hashCode int
The hash code for this object.
no setterinherited
key Key?
Controls how one widget replaces another widget in the tree.
layers List<MapLayer>
The collection of map shape layer in which geographical rendering is done.
runtimeType Type
A representation of the runtime type of the object.
no setterinherited


createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
createState() State<SfMaps>
Creates the mutable state for this widget at a given location in the tree.
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
toStringShort() String
A short, textual description of this widget.


operator ==(Object other) bool
The equality operator.