Skip to main content
Unified_Map
layers

Tile Layer

TileLayer keeps flutter_map's name and parameters — urlTemplate, subdomains, wmsOptions, tms, zoomOffset, tileBounds, minNativeZoom / maxNativeZoom, … — but on the native maps the tiles are not drawn by a Dart tile engine: the platform builds the URL, fetches and renders each tile itself, above its own base map. On web, Windows and Linux this is flutter_map's own layer, pixel for pixel.

UnifiedMap(
  options: MapOptions(initialCenter: brussels, initialZoom: 6),
  children: [
    TileLayer(
      urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
      maxNativeZoom: 19,
    ),
    // … markers, polylines, polygons, circles
  ],
)

Why it differs on iOS and Android​

On flutter_map the tile layer is the map. On the native maps the base map — Google Maps on Android, MapKit on iOS and macOS — is already there, and TileLayer draws on top of it as a native tile overlay:

Android (Google Maps)iOS, macOS (MapKit)Web, Windows, Linux (flutter_map)
Base mapGoogle's, under the tilesApple's, under the tilesnone — the tiles are the map
Hiding the baseMAP_TYPE_NONE while the layer is showntile overlay with canReplaceMapContentn/a
Fade-in (TileDisplay.fadeIn)fades new tiles in (its duration is ignored)shows new tiles at oncefull flutter_map behaviour
Tile cachethe platform's HTTP cachethe platform's HTTP cacheNetworkTileProvider's cache

Set nativeParams.replacesBaseMap to hide the base map under the tiles and let them cover the whole view.

Where the tiles come from​

  • The URL is always built with flutter_map's rules (urlTemplate, subdomains, tms, zoomReverse, zoomOffset, additionalOptions, tileBounds, retinaMode). With the default NetworkTileProvider the platform fetches the tiles itself, with the provider's headers.
  • Any other TileProvider — and wmsOptions — goes through a Dart tile bridge: the platform asks the core for each tile, the core loads it with TileProvider.getImage and encodes it as PNG. Correct everywhere, but slower than the native fetch.
  • keepBuffer, panBuffer, tileBuilder, evictErrorTileStrategy and tileUpdateTransformer drive flutter_map's tile engine only: the native platforms cache, prefetch and retry on their own (tiles are images there, not widgets). Send a value on the reset stream to drop the platform's tile cache and reload the visible tiles.
  • errorImage is drawn natively for failed tiles; errorTileCallback receives the failed tile's coordinates.
  • userAgentPackageName sets the User-Agent header to flutter_unified_map (<package>), unless the provider's headers set one (on the web the browser's own is used).

Zoom levels and tile dimensions​

minZoom / maxZoom hide the layer outside their range. Above maxNativeZoom the last native level is scaled up, below minNativeZoom the first one is scaled down — the same on every backend. tileDimension 512 or 1024 follows the Mapbox convention: each tile covers the extent of a 256 tile one or two levels lower, so use zoomOffset: -1 / -2 with them.

Raw flutter_map layers​

App code can put a raw flutter_map layer inside UnifiedMap with FlutterMapLayer(child: ...):

  • on web, Windows and Linux it is drawn inside the map;
  • on the native maps (Android, iOS, macOS) it is ignored.

Use it to share code with an existing flutter_map app while the native backends take over.

On this page