MapTileLayer class Null safety

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

The 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 urlTemplate itself as mentioned in above example. Please note that the format may vary between the each map providers. 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 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, initialFocalLatLng and 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 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: '{z}/{x}/{y}.png',
          initialFocalLatLng: MapLatLng(-23.698042, 133.880753),
          initialZoomLevel: 3

See also:



MapTileLayer({Key? key, required String urlTemplate, MapLatLng initialFocalLatLng = const MapLatLng(0.0, 0.0), int initialZoomLevel = 1, MapTileLayerController? controller, List<MapSublayer>? sublayers, int initialMarkersCount = 0, MapMarkerBuilder? markerBuilder, IndexedWidgetBuilder? markerTooltipBuilder, MapTooltipSettings tooltipSettings = const MapTooltipSettings(), MapZoomPanBehavior? zoomPanBehavior, WillZoomCallback? onWillZoom, WillPanCallback? onWillPan})
Creates a MapTileLayer.


controller MapTileLayerController?
Provides options for adding, removing, deleting, updating markers collection and converting pixel points to latitude and longitude. [...]
hashCode int
The hash code for this object. [...]
@nonVirtual, read-only, inherited
initialFocalLatLng MapLatLng
Represents the initial focal latitude and longitude position. [...]
initialMarkersCount int
Option to set markers count initially. It cannot be be updated dynamically. [...]
final, inherited
initialZoomLevel int
Represents the initial zooming level. [...]
key Key?
Controls how one widget replaces another widget in the tree. [...]
final, inherited
markerBuilder MapMarkerBuilder?
Returns the MapMarker for the given index. [...]
final, inherited
markerTooltipBuilder IndexedWidgetBuilder?
Returns the widget for the tooltip of the MapMarker. [...]
final, inherited
onWillPan WillPanCallback?
Called whenever panning is happening. [...]
final, inherited
onWillZoom WillZoomCallback?
Called whenever zooming is happening. [...]
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited
sublayers List<MapSublayer>?
Collection of MapShapeSublayer, MapLineLayer, MapPolylineLayer, MapPolygonLayer, MapCircleLayer, and MapArcLayer. [...]
final, inherited
tooltipSettings MapTooltipSettings
Customizes the bubble, marker, and shape tooltip's appearance. [...]
final, inherited
urlTemplate String
URL template to request the tiles from the providers. [...]
zoomPanBehavior MapZoomPanBehavior?
Enables zooming and panning in MapShapeLayer and MapTileLayer. [...]
final, inherited


build(BuildContext context) Widget
Describes the part of the user interface represented by this widget. [...]
createElement() StatelessElement
Creates a StatelessElement to manage this widget's location in the tree. [...]
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent 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 =}) 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. [...]
@nonVirtual, inherited