Subdomains (subdomains)

Takes a list of strings specifying the available subdomains. For example:

        subdomains: ['a', 'b', 'c'],

One will be chosen differently every request by the tile provider to replace the '{s}' part of the urlTemplate.

If you are not sure of the correct values for your server, don't specify anything. For example, the urlTemplate used in the example above will work without the '{s}' part and any subdomains specified.

Tile Bounds (tileBounds)

Takes a LatLngBounds to restrict the layer to only loading tiles within that area. For example:

        tileBounds: LatLngBounds(
            LatLng(32.2934590056236, 24.328924534719548),
            LatLng(21.792152188247265, 37.19854583903912),
        ),

will restrict the tiles to only loading Egypt (a square-ish country). Note that the map can still be moved freely outside of this range.

An example use-case might therefore be loading a specialised map for a region and just a basic map style elsewhere (different urlTemplates). In this case, the bounded layer should go beneath the unbounded layer. Setting backgroundColor: Colors.transparent is also necessary on the bounded layer to ensure the other layer is visible elsewhere.

Error/Fallback Tile (errorImage)

Takes an ImageProvider, such as a NetworkImage, to use if the tile cannot be fetched using the templateUrl. The size of the returned image should be the same as the tile size. For example:

        errorImage: const NetworkImage('https://tile.openstreetmap.org/18/0/0.png'),

will use a sea tile on every tile that cannot be fetched.

This is an optional parameter that has no default. If this is not specified, and tiles are unable to be fetched, then the background color.

Tile Size (tileSize)

Takes a double number specifying the width and height (in pixels) of each tile. As tiles are always square, only one number is needed.

This defaults to 256, as most tile servers serve 256x256px tiles.

Custom Tile Builder (tileBuilder)

Takes a callback function, in the format Widget Function(BuildContext context, Widget tileWidget, Tile tile). For example:

        tileBuilder: (context, widget, tile) =>
          Stack(
            fit: StackFit.passthrough,
            children: [
              widget,
              Center(
                child:
                  Text('${tile.coords.x.floor()} : ${tile.coords.y.floor()} : ${tile.coords.z.floor()}'),
              ),
            ],
          );

will show the tile's coordinate on the tile.

There is also tilesContainerBuilder available, which works slightly differently, but is recommended when the same builder can be used on every tile, for performance reasons.

There are predefined tile builders available, such as a dark mode emulator and a loading time debugger.

Reset Stream (reset)

Takes a Stream<void>?, that causes the layer to 'reset' when an event is received. This might be necessary after updating the templateUrl. For example:

       reset: resetController.stream,
  
  // Elsewhere     
  final StreamController<void> resetController = StreamController.broadcast();
  void resetMap() => resetController.add(null);

URL Template (urlTemplate)

This parameter is not strictly required, but the map is essentially useless without it specified with a valid URL.

Takes a string that is a valid URL, which is the template to use when the tile provider constructs the URL to request a tile from a tile server. For example:

will use the OpenStreetMap Tile Server.

The '{s}', '{z}', '{x}' & '{y}' parts indicate where to place the subdomain, zoom level, x coordinate, and y coordinate respectively. Not providing at least the latter 3 parts won't necessarily throw an error, but the map won't show anything.

Package Name (userAgentPackageName)

Takes a String, which should be the unique package name (eg. com.example.app). For example:

This string is used to construct a 'User-Agent' header, sent with all tile requests (on platforms other than the web, due to Dart limitations), necessary to prevent blocking by tile servers.

Constructed agents are in the format: 'flutter_map (packageName)'. If the package name is not specified, 'unknown' is used in place.

Tile Provider (tileProvider)

For more information, see:

Retina Mode (retinaMode)

If true, the providers should request four tiles of half the specified size and a bigger zoom level in place of one to utilize the high resolution. In this case, you should set MapOptions's maxZoom should be maxZoom - 1 instead.

For example, this is the recommended setup:

A tile layer displays raster map tiles in a grid pattern, from a tile source such as a remote server or file system. This might look something like this:

The tileProvider parameter in TileLayer takes a TileProvider object specifying a tile provider to use for that layer.

This has a default of NetworkNoRetryTileProvider, which is recommended for most setups for better performance, unless your tile server is especially unreliable, or you need a local tile provider.

Custom TileProviders can be implemented by your application or other libraries. These may not conform to the usual rules above, and may additionally have their own parameters.

Network Tile Providers

Network tile providers can take a Map<String, String> of custom headers. Note that the user agent that is automatically generated will not override any 'User-Agent' header if specified here. On the web, the 'User-Agent' header is not sent, as the browser controls the user agent.

Whilst not on the web, network tile providers can take a custom HttpClient/RetryClient, if you need to use it for whatever reason.

NetworkNoRetryTileProvider()

This is the default tile provider.

This tile provider uses the templateUrl to get the appropriate tile from the Internet, and it won't retry the request if it fails.

There is no guarantee about the default caching behaviour, but tiles should be cached until an application restart.

NetworkTileProvider()

This tile provider uses the templateUrl to get the appropriate tile from the Internet, but it will retry the request as specified in the RetryClient (which can be customised as needed when not on the web).

There is no guarantee about the default caching behaviour, but tiles should be cached until an application restart.

Local Tile Providers

These tile providers use the templateUrl to get the appropriate tile from the asset store of the application, or from a file on the users device, respectively

AssetTileProvider()

This tile providers uses the templateUrl to get the appropriate tile from the asset store of the application.

FileTileProvider()

This tile providers uses the templateUrl to get the appropriate tile from the a path/directory/file on the user's device - either internal application storage or external storage.

Offline Mapping

Bundled Map Tiles

If you have a set of custom raster tiles that you need to provide to all your users, you may want to consider bundling them together, to make a them easier to deploy to your users. Note that this is different to the #caching section below.

There is essentially two options for doing this:

• Using AssetTileProvider, you can bundle a set of map tiles and register them as an asset within your app's pubspec.yaml. This means that they will be downloaded together with your application, keeping setup simple, but at the expense of a larger application bundle size.

• Using FileTileProvider, you can bundle a set of map tiles and store them on a remote web server, that can be downloaded from later. This means that the setup may be more complicated for users, but the application's bundle size will be much smaller.

Either way, the filesystem should be structured like this: 'offlineMap/{z}/{x}/{y}.png', where every .png image is a tile.

If you have a raster-format .mbtiles file, for example from TileMill, you should use mbtilesToPngs to convert it to the correct structure first. Alternatively, you can use an external package such as 'flutter_mbtiles_extractor' to extract during runtime.

Caching & Bulk Downloading

The community maintained plugin flutter_map_tile_caching provides advanced caching and bulk downloading capability, which handles many surrounding and supporting features for you and your app, with minimal implementation effort.

However, using simpler packages in a DIY solution can be a better option in some cases. You'll need to implement a custom TileProvider backed by an alternative image provider or cache lookup system: see Creating New Tile Providers.

To help choose whether FMTC or DIY is more appropriate for your usecase, please see:

If you prefer to offer a set of map tiles to all your users before runtime, consider using the #bundled-map-tiles solution instead.