Tile Layer

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(
  urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
  userAgentPackageName: 'dev.fleaflet.flutter_map.example',
  // Plenty of other options available!
),
  • URL Template (required, except when using WMS) Choose a suitable tile server for your app

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

  • 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)

If you need to squeeze out as much performance as possible, or you're noticing the tile loading seems a little slow:

  • Make sure the FlutterMap is rebuilt as few times as possible

  • Construct the TileProvider yourself, outside of the build method if possible, so it is reconstructed as few times as possible Some tile providers may perform more expensive logic when they are constructed, and if the provider is frequently reconstructed, this can add up.

  • If the TileProvider supports it (as NetworkTileProvider does), construct a single HTTP Client/HttpClient outside the build method and pass it to the tile provider - especially if you're unable to do the tip above Using a single HTTP client allows the underlying socket connection to the tile server to remain open, even when tiles aren't loading. When tiles are loaded again, it's much faster to communicate over an open socket than opening a new one. In some cases, this can take hundreds of milliseconds off tile loading!

  • Reduce panBuffer to 0 This reduces the number of network requests made, which may make those requests that are made for more important tiles faster.

Main Parameters

URL Template

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:

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.

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.

Note that where tiles are larger than the standard x256px (such as x512px), retina mode can help make them appear very similar to x256px tiles, but still retain the other benefits of larger tiles. In this case, consider fixing retinaMode to true, depending on your own tests. See tileSize for more information.

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).

userAgentPackageName

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

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

Tile Providers

tileSize

Some tile servers will use 512x512px tiles instead of 256x256px, such as Mapbox. Using these larger tiles can help reduce tile requests, and when combined with Retina Mode, it can give the same resolution.

To use these tiles, set tileSize to the actual dimensions of the tiles (otherwise they will appear to small), such as 512. Also set zoomOffset to the result of -((d/256) - 1) - ie. -1 for x512px tiles (otherwise they will appear at the wrong geographical locations).

The {d} placeholder/parameter may also be used in the URL to pass through the value of tileSize.

panBuffer

To make a more seamless experience, tiles outside the current viewable area can be 'preloaded', with the aim of minimizing the amount of non-tile space a user sees.

panBuffer sets the number of surrounding rows and columns around the viewable tiles that should be loaded, and defaults to 1.

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:

Last updated

Was this helpful?