Tile Layer
Last updated
Was this helpful?
Last updated
Was this helpful?
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. It is NOT free to use. 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.
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 following these steps for every tile layer.
flutter_map doesn't provide tiles, so you'll need to bring your own raster tiles! There's multiple different supported sources.
If you have a URL with placeholders for X, Y, and Z values, this is probably what you need to set up. This is the most common format for raster tiles, although many satellite tiles will instead use WMS.
Set the urlTemplate parameter to the template provided by the tile server - usually it can be copied directly from an account portal or documentation. You may also need to copy an API/access key.
As well as the standard XYZ placeholders in the template, the following placeholders may also be used:
{s}: subdomains (see below)
{r}: native retina mode - see step 4 for more information
{d}: reflects the tileDimension property (see below)
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.
It's important to identify your app to tile servers using the HTTP 'User-Agent' header (if they're not your own, and especially if their free or their ToS specifies to do so). This avoids potential issues with the tile server blocking your app because they do not know why so many tiles are being requested by unidentified clients - this can escalate to flutter_map being blocked as a whole if too many apps do not identify themselves
Set the userAgentPackageName parameter to your app's package name (such as com.example.app or any other unique identifying information). flutter_map will identify your client to the server via the header as:
flutter_map (<packageName or 'unknown'>)
In some cases, you may be able to skip this step:
Your app runs solely on the web: the 'User-Agent' header cannot be changed, and will always identify your users' browsers
The tile server is your own, or you are using entirely offline mapping
The TileProvider is responsible for fetching tiles for the TileLayer. By default, the TileLayer creates a NetworkTileProvider every time it is constructed. TileProviders are attached to the lifecycle of the TileLayer they are used within, and automatically disposed when their TileLayer is disposed.
However, this can cause performance issues or glitches for many apps. For example, the HTTP client can be manually constructed to be long-living, which will keep connections to a tile server open, increasing tile loading speeds.
See Tile Providers for more information about tile providers generally.
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.
To enable retina mode in these circumstances, use the following:
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.
Set the maxNativeZoom parameter to the maximum zoom level covered by your tile source. This will make flutter_map scale the tiles at this level when zooming in further, instead of attempting to load new tiles at the higher zoom level (which will fail).
You can also set MapOptions.maxZoom, which is an absolute zoom limit for users. It is recommended to set this to a few levels greater than the maximum zoom level covered by any of your tile layers.
panBufferTo 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.
Specifying a panBuffer too high may result in slower tile requests for all tiles (including those that are visible), and a higher load on the tile server. The effect is amplified on larger map dimensions/screen sizes.
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:
If you're not using a different tile provider, such as one provided by a plugin or one for offline mapping, then installing and using the official CancellableNetworkTileProvider plugin may be beneficial, especially on the web. See for more information.
