Tile Layer

You must comply with the appropriate restrictions and terms of service set by your tile server. Always read the ToS before using a tile server. Failure to do so may lead to any punishment, at the tile server's discretion.

This library and/or the creator(s) are not responsible for any violations you make using this package.

The OpenStreetMap Tile Server (as used below) ToS can be found here. Other servers may have different terms.

The basis of any map is a TileLayer, which displays square raster images in a continuous grid, sourced from the Internet or a local file system.

flutter_map supports WMS Usage, but most map tiles are accessed through Slippy Map/CARTO/XYZ URLs, as described here.

TileLayer class - flutter_map library - Dart API

TileLayer(
  urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
  userAgentPackageName: 'dev.fleaflet.flutter_map.example',
  // Plenty of other options available!
),

Although setting up a basic tile layer couldn't be simpler, it helps to spend a little bit more time fine-tuning it! We recommend covering this list at least, for every tile layer.

• URL Template Choose a suitable tile server for your app

• userAgentPackageName Always set userAgentPackageName, even though it is technically optional

• Subdomains Consider whether you should set subdomains for your template URL

• Retina Mode If your tile server supports retina tiles natively, set up the retinaMode property

• CancellableNetworkTileProvider Especially on web, consider using this more advanced TileProvider to improve performance
• maxNativeZoom Set the maximum zoom level that the tile server supports to prevent flutter_map from trying to exceed this (especially when not set appropriately in MapOptions.maxZoom)

URL Template

This parameter must be specified unless wmsOptions is specified.

The URL template is a string that contains placeholders, which, when filled in, create a URL/URI to a specific tile.

Specifically, flutter_map supports the Slippy Map format, sometimes referred to as CARTO or Raster XYZ. Tiles are referred to by their zoom level, and position on the X & Y axis. For more information, read How Does It Work?.

These templates are usually documented by your tile server, and will always include the following placeholders:

• {x}: x axis coordinate

• {y}: y axis coordinate

• {z}: zoom level

Sometimes, they also include:

• {s}: Subdomains

• {r}: Retina Mode

Additional placeholders can also be added freely to the template, and are filled in with the specified values in additionalOptions. This can be used to easier add switchable styles or access tokens, for example.

Subdomains

Some tile servers provide mirrors/redirects of the main tile server on/via subdomains, such as 'a', 'b', 'c'.

These were necessary to bypass browsers' limitations on simultaneous HTTP connections, thus increasing the number of tiles that can load at once.

To use subdomains, add the {s} placeholder, and specify the available subdomains in TileLayer.subdomains. flutter_map will then fill the placeholder with one of these values based on internal logic.

Subdomains are now usually considered redundant due to the usage of HTTP/2 & HTTP/3 which don't have the same restrictions.

Usage of subdomains will also hinder Flutter's ability to cache tiles, potentially leading to increased tile requests and costs.

If the server supports HTTP/2 or HTTP/3 (how to check), avoid using subdomains.

Retina Mode

Retina mode improves the resolution of map tiles, an effect particularly visible on high density (aka. retina) displays.

Raster map tiles can look especially pixelated on retina displays, so some servers support high-resolution "@2x" tiles, which are tiles at twice the resolution of normal tiles.

Where the display is high density, and the server supports retina tiles - usually indicated by an {r} placeholder in the URL template - it is recommended to enable retina mode.

Therefore, where {r} is available, it is recommended to call the method RetinaMode.isHighDensity with the current BuildContext, and pass the result to TileLayer.retinaMode. This will enable retina mode on retina displays by filling the {r} placeholder with "@2x".

Emulation

It is also possible to emulate retina mode, even when the server does not natively support it. If retinaMode is true, and no {r} placeholder is present, flutter_map will emulate it by requesting four tiles at a larger zoom level and combining them together in place of one.

Emulating retina mode has multiple negative effects:

• it increases tile requests

• it likely causes text/labels and POI markers embedded in the tiles to become smaller and unreadable

• it decreases the effective maximum zoom by 1

Therefore, carefully consider whether emulating retina mode is appropriate for your application, and disable it if necessary. Always prefer native retina tiles if they are available.

Fallback URL Template

It's also possible to specify a fallbackUrl template, used if fetching a tile from the primary urlTemplate fails (which has the same format as this).

Specifying a fallbackUrl does have negative effects on performance and efficiency. Avoid specifying fallbackUrl unless necessary.

See in-code documentation and Tile Providers for more information.

Some TileProviders may not support/provide any functionality for fallbackUrl template.

userAgentPackageName

Although it is programatically optional, always specify the userAgentPackageName argument to avoid being blocked by your tile server.

This parameter should be passed the application's package name, such as 'com.example.app'. This is important to avoid blocking by tile servers due to high-levels of unidentified traffic. If no value is passed, it defaults to 'unknown'.

This is then formatted into a 'User-Agent' header, and appended to the TileProvider's headers map, if it is not already present.

This is ignored on the web, where the 'User-Agent' header cannot be changed due to a limitation of Dart/browsers.

Tile Providers

If a large proportion of your users use the web platform, it is preferable to use CancellableNetworkTileProvider, instead of the default NetworkTileProvider. It may also be beneficial to use this tile provider on other platforms as well.

See CancellableNetworkTileProvider for more information.

Need more control over how the URL template is interpreted and/or tiles are fetched? You'll need to change the TileProvider.

pageTile Providers

Tile Update Transformers

TileUpdateTransformer(s) is a power-user feature. Most applications won't require it.

A TileUpdateTransformer restricts and limits TileUpdateEvents (which are emitted 'by' MapEvents), which cause tiles to update.

For example, a transformer can delay (throttle or debounce) updates through one of the built-in transformers, or pause updates during an animation, or force updates even when a MapEvent wasn't emitted.

For more information, see:

TileUpdateTransformer typedef - flutter_map library - Dart API