Raster tiles are the 'older' type of tile, and are raster images (usually .png or .jpg). These tiles are good because they can render quickly and easily, can be viewed without special software, and are readily available from most mapping services. As such, this makes them the popular choice for beginners.

However, raster tiles cannot be easily themed: a theme needs a whole new set of map tiles. This makes apps using light and dark themes have mismatching maps. As well as this, raster tiles usually have larger file sizes meaning slower download times, and they can become blurred/pixelated when viewed at a larger scale: a problem for users when zooming between zoom levels. Another issue is that shapes/text inside tiles cannot be rotated, hence the name 'static tiles': therefore, rotating the map will not rotate the name of a road, for example.

Vector Tiles

Vector tiles can be considered the 'newer' standard. These images might contain a specialised format (such as .pbf) dictating the mathematics and coordinates used to draw lines and shapes. Because these tiles are drawn at render time instead of at request/server time, theming can be used to make the map fit in better with an app's theme. The math-based image means that the images/tiles can be scaled without any loss of clarity.

However it does add complexity to the rendering process as each element needs to be parsed and painted individually, meaning an impact to performance. Text elements and certain shapes can also be rotated (unlike raster tiles) to match the user's orientation, not the orientation of the map; but calculating this rotation needs to be done every frame, meaning an even larger impact on performance.

Using Vector Tiles

Due to the complications mentioned above, 'flutter_map' does not natively support vector tiles. However, vector tiles can be used with a community maintained plugin (vector_map_tiles) to do this.

If the map is displayed lazily in something like a PageView, changing the page and unloading the map will cause it to reset to its initial positioning.

To prevent this, set MapOptions.keepAlive true, which will activate an internal AutomaticKeepAliveClientMixin. This will retain the internal state container in memory, even when it would otherwise be disposed.

Constraining the camera vertically/latitudinally

It's now possible to remove the grey edges that appear at the top and bottom of the map when zoomed far out.

To do this, set the MapOptions.cameraConstraint parameter:

Feature layers & multi-worlds

Each square of map that is repeated longitudinally is referred to as a "world". By default, the feature layers (for example, PolygonLayer, PolylineLayer, CircleLayer, and MarkerLayer) will repeat their features across the layers, so that each world looks identical.

In the PolylineLayer & PolygonLayer, this can be disabled by setting the drawInSingleWorld property.

Styles

Stadia Maps offers a variety of ready-made map styles that don't require customization. URLs are found with the style: see the available map styles. The URL should be used as above.

Vector Usage

Stadia Maps' also provides vector tiles. For more information about using vector tiles, please see Using Vector Tiles.

However, please note that this method of integration is still experimental. Many of the Stadia Maps styles utilize advanced features of the Mapbox GL JSON style language which are not yet well-supported.

CORS

On the web platform, CORS restrictions designed to protect resources on websites and control where they can be loaded from. Some tile servers may not be intended for external consumption, or may be incorrectly configured, which could prevent tiles from loading. If tiles load correctly on platforms other than the web, then this is likely the cause.

See the Flutter documentation for more details. We load images using a standard Image widget.

If you're running on the web, some features may not work as expected due to limitations or bugs within Flutter. For example, check the Polygon Layer documentation.

Alignment

The marker widget will be centered over the geographic coordinate by default. However, this can be changed with the alignment argument, which aligns the widget relative to the point.

The center of rotation when rotate is true will be the point.

The default alignment for all Markers within a MarkerLayer can be set by changing the same property on the MarkerLayer.

Rotation

It is possible to enable the Marker to automatically counter-rotate to the camera's rotation, to ensure it remains facing upwards, via the rotate argument.

The default alignment for all Markers within a MarkerLayer can be set by changing the same property on the MarkerLayer.

Handling Gestures

There is no built-in support to handle gestures on Markers, such as taps. However, this is easy to implement using a standard GestureDetector.

Prebuilt Artifacts

If you can't build from source for your platform, our GitHub Actions CI system compiles the example app to GitHub Artifacts for Windows, Web, and Android.

The Windows and Android artifacts just require unzipping and installing the .exe or .apk found inside.

The Web artifact requires unzipping and serving, as it contains more than one unbundled file. You may be able to use dhttpd for this purpose.

Build From Source

If you need to use the example app on another platform, you can build from source, using the 'example' directory of the repository.

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

RichAttributionWidget

An animated, interactive attribution layer that supports both logos/images (displayed permanently) and text (displayed in a popup controlled by an icon button adjacent to the logos).

It is heavily customizable (in both animation and contents), and designed to easily meet the needs of most ToSs out of the box.

For more information about configuration and all the many options this supports, see the in-code API documentation.

SimpleAttributionWidget

We also provide a more 'classic' styled box, similar to those found on many web maps. These are less customizable, but might be preferred over RichAttributionWidget for maps with limited interactivity.

CircleLayers and CircleMarkers support hit detection and interactivity.

2. Hooking Into Inherited State

Then, there are three possible methods that could be used to retrieve separate 'aspects' of the state of the map.

Calling these inside a build method will also cause the layer to rebuild automatically when the depended-on aspects change.

• throw CachedMapTileReadFailure with as much information as possible from readTile

• repair or replace the tile with a fresh & valid one

• ensure other mechanisms are resilient to corruption

This could occur due to corruption, for example a power cut, a sudden storage issue, or an intentional modification that did not comply with the expected specification.

It is not the provider's responsibility to check that stored tile bytes are valid. Providers may return invalid or undecodable bytes to tile providers, which they should handle gracefully by falling back to a non-caching alternative to retrieve a tile, and safely updating the invalid stored tile.

To create your own usable TileProvider, the first step is making a class that extends the abstract class, and adding a constructor.

The constructor should accept an argument of super.headers, without a constant default.

2. Setup Tile Retrieval

TileProviders must implement a method to return an ImageProvider (the image of a tile), given its coordinates and the TileLayer it is used within.

There's two methods that could be called by flutter_map internals to retrieve a tile: getImage or getImageWithCancelLoadingSupport.

Prefer overriding getImageWithCancelLoadingSupport for TileProviders that can cancel the loading of a tile in-flight, if the tile is pruned before it is fully loaded. An example of a provider that may be able to do this is one that makes HTTP requests, as HTTP requests can be aborted on the web (although Dart does not 'natively' support it yet, so a library such as Dio is necessary). Otherwise, getImage must be overridden.

Tile providers can support the MapCachingProvider contract/interface to support built-in caching. See Caching Providers.

(Optionally) Override URL Generation

Some custom TileProviders may want to change the way URLs are generated for tiles, given a coordinate.

It's possible to override:

• how the urlTemplate's placeholders are populated: populateTemplatePlaceholders

• the values used to populate those placeholders: generateReplacementMap

• the generation method itself: getTileUrl and/or getTileFallbackUrl

@josxha

It does, however, come at the expense of usage of on-device storage capacity.

Offline mapping and caching can also be implemented in other ways. See Offline Mapping for more information.

Configuring the built-in provider

To configure the default provider, provide arguments to the getOrCreateInstance factory constructor. Usually this is done when constructing the TileLayer/TileProvider:

By default, caching occurs in a platform provided cache directory. The operating system may clear this at any time.

By default, a 1 GB (soft) limit is applied to the built-in caching. This limit is only applied when the cache provider is initialised (usually when the first tiles are loaded on each app session).

HTTP headers are used to determine how long a tile is considered 'fresh' - this fulfills the requirements of many tile servers. However, setting overrideFreshAge allows the HTTP headers to be overridden, and the tile to be stored and used for a set duration.

The tileKeyGenerator can be customized. The callback accepts the tile's URL, and converts it to a key used to uniquely identify the tile. By default, it generates a UUID from the entire URL string. However, in some cases, the default behaviour should be changed:

Deleting the cache

With the default BuiltInMapCachingProvider, it is possible to delete the cache contents in two ways:

• When the app is running, destroy the current instance and set the deleteCache argument to true (then optionally create a new instance if required, which happens automatically on the next tile load by default)

• When the app is not running, users may delete the storage directory

  • If the default cache directory is used, users may do this by 'clearing the app cache' through their operating system, for example. On some platforms, this may need to be done manually (which may be difficult for less technical users), whilst on others, it may be a simple action.

Using other providers

You can also use any other MapCachingProvider implementation, such as provided by plugins, or create one yourself! They may support the web platform, unlike the built-in cache.

You should check that plugin's documentation for information about initialisation & configuration. You will always need to pass it to the cachingProvider argument of a compatible TileProvider.

Disabling built-in caching

If you prefer to disable built-in caching, use the DisabledMapCachingProvider on each tile provider:

To display their map tiles, Mapbox usually provides a 'Style URL' for map styles. However, to integrate with 3rd-party APIs, they also provide a 'CARTO Integration URL', and tiles requested through this endpoint consume the 'Static Tiles API' quota. This URL needs no extra configuration to integrate with flutter_map.

Integration

Custom Styles

Mapbox supports creating and using custom styled maps through Studio.

1. Create a custom style using the editor

2. Click "Share...", or the share icon

3. Choose between Draft or Production

4. Scroll to the bottom of the dialog, and choose Third Party

5. Select "CARTO" from the dropdown menu

6. Click the copy button to copy the template URL, then paste it into your TileLayer

Configuring Retina Mode

The URL includes an '@2x' string, which forces usage of high-definition tiles on all displays, without extra setup.

Should you need to let flutter_map interfere, and only use retina tiles on retina/high-density displays, replace it with the '{r}' placeholder, then see for more information.

Other configurations

The maximum zoom level that Mapbox supports is 22, so it is recommended to set maxNativeZoom or maxZoom as such.

Adding Attribution

Prebuilt Styles

Mapbox offers a variety of ready-made map styles that don't require customization. An example URL can be found in the example here.

This URL should be used as above, although you may need to insert the placeholders manually.

Thanks to Luka Glušica for discovering the basic initial implementation.

This feature was bounty-funded, thanks to our generous Supporters, and the community! We hope to open more bounties in future.

The old method of picking a placement algorithm has been deprecated and been replaced with a new, extensible system - it's still just as easy to use as the old one

See how to migrate to the new system below.

Follow the new guide to setup a TileLayer as we recommend: . More to come soon!

In future, we may block users which do not set a valid UA identifier for this server.

For more information, see Using OpenStreetMap (direct).

Here's the mapping of old enum values to new objects:

• old default / .centroid -> .centroid() (new algorithm)

• .centroidWithMultiWorld -> .simpleMultiWorldCentroid()

• .polylabel -> .polylabel()

• (new) .simpleCentroid()

This breaks a large number of coordinate handling functions, such as those converting between geographic coordinates and screen space coordinates (the changed ones) in the MapCamera. We've also renamed some of these functions to remove references to 'point' and replace them with 'offset'.

Most migrations should be self explanatory. If necessary, you can view the PR to see what happened to a method you were using - there's very likely a close replacement! Some methods have been moved to internal usage only, but there's always easy alternatives.

Some external libraries still use the previous objects, and some of our use-cases are just not yet ready to be replaced by these options yet, so you may still find some of the old objects hiding around the codebase. IntegerBounds is internal only.

Simplification algorithms reduce the number of points in each line by removing unnecessary points that are 'too close' to other points which create tiny line segments invisible to the eye. This reduces the number of draw calls and strain on the raster/render thread. This should have minimal negative visual impact (high quality), but should drastically improve performance.

For this reason, polygons can be more simplified at lower zoom levels (more zoomed out) and less simplified at higher zoom levels (more zoomed in), where the effect of culling on performance improves and trades-off. This is done by scaling the simplificationTolerance parameter (see below) automatically internally based on the zoom level.

Polygons (and similar other features) are usually drawn directly onto a Canvas, using built-in methods such as drawPolygon and drawLine. However, these can be relatively slow, and will slow the raster thread when used at a large scale.

Therefore, to improve performance, it's possible to optionally set the useAltRendering flag on the PolygonLayer. This will use an alternative, specialised, rendering pathway, which may lead to an overall performance improvement, particularly at a large scale.

There's two main steps to this alternative rendering algorithm:

1. Cut each Polygon into multiple triangles through a process known as triangulation. flutter_map uses an earcutting algorithm through dart_earcut (a port of an algorithm initially developed at Mapbox intended for super-large scale triangulation).

2. Draw each triangle onto the canvas via the lower-level, faster drawVertices method. Borders are then drawn as normal.

This gives the best performance, and works on the web. This is the default when targeting the web.

However, it yields unintended results in certain edge cases when polygons intersect when Inverted Filling is used, or when polygon holes can intersect with other holes.

The map's camera - or MapCamera - is an object that holds information to be read about the map's current viewport, such as:

• the coordinates of the geographic location at the center of the map

• the current rotation of the map (in degrees, where 0° is North)

• the current zoom level of the map

For example:

Controller

Similarly to other map client projects, the controller - MapController - allows the map's viewport/camera to be modified/set using methods, such as:

• move the camera to a new location and zoom level, using either:

  • move, which accepts a new center coordinate and zoom level

  • fitCamera, which allows more advanced positioning using coordinate boundaries and screen-space padding

• rotate the camera to a new number of degrees from North

For example:

Accessing the 'aspects'

Together, the MapCamera and MapController are two aspects of the MapInheritedModel.

Reacting to map events

To imperatively react to changes to the map camera, there's multiple methods available.

Simple events

If you prefer a callback-based pattern and need to capture user interaction events with the widget (with limited information about the event or its effect on the map itself), the following callbacks are available through MapOptions:

• onTap

• onLongPress

• onPointerDown/onPointerMove/onPointerUp/onPointerHover/onPointerCancel

These callbacks are also available, which are not strictly caused by user interaction events and give information about the map, but are provided for ease-of-use:

• onPositionChanged: called when the map moves

• onMapReady: called when the MapController is attached

For example:

Multiple or complex event handling

There's two methods to handle raw MapEvents, which are emitted whenever the MapCamera changes, and contain detailed information, such as the source of the event, and, for some events, the old and new camera.

Caching

Caching is used usually to improve user experience by reducing network waiting times, not necessarily to prepare for no-Internet situations. Caching can be temporary (eg. in-memory/session-only, where the cache is cleared after the app is closed), or longer-term (eg. app cache, where the OS takes responsibility for clearing the app cache when necessary/when requested).

Temporary caching is automatically implemented by Flutter's ImageCache when using tile providers backed by ImageProviders (such as the NetworkTileProvider).

However, many tile servers, such as the OpenStreetMap tile server, will require you to implement longer-term caching!

Since v8.2.0, flutter_map provides Caching functionality built-in - this automatically enables long-term caching, and is extensible to allow other caching providers to be used. The default built-in provider satisfies many requirements of both users and tile servers automatically.

If you'd prefer not to use built-in caching, you can:

• Try another MapCachingProvider implementation if you still only need simple caching These are compatible with the standard NetworkTileProvider (and cancellable version), as with built-in caching, but use a different storage mechanism. You can create an implementation yourself, or use one provided by a 3rd-party/plugin. See Using other providers for more info.

• Use a caching HTTP client NetworkTileProvider.httpClient can be used to set a custom HTTP client. Some packages, such as 'package:http_cache_client', offer clients which perform HTTP caching, similar to built-in caching.

• Use a different TileProvider Tile providers have full control over how a tile is generated to be displayed, and so there are many possibilities to integrate caching.

  • Create a with a caching ImageProvider (either custom or using a package such as '')

  • Use Caching created prior to built-in caching, lightweight and MIT licensed, but with more pre-provided options than built-in caching through 3rd-party storage implementations

  • Use Supports very advanced caching use-cases and , but GPL licensed

Bulk Downloading

Bulk downloading is used to prepare for known no-Internet situations by downloading map tiles, then serving these from local storage.

Bulk downloading is more complex than Caching, especially for regions that are a non-rectangular shape. Implementing this can be very time consuming and prone to issues.

The community maintained plugin 'flutter_map_tile_caching' includes advanced bulk downloading functionality, of multiple different region shapes, and other functionality. It is however GPL licensed. To help choose whether FMTC or DIY is more appropriate for your use case, please see:

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. Bundles can be provided in two formats.

Contained

Container formats, such as the traditional MBTiles, or the more recent PMTiles, store tiles usually in a database or binary internal format.

These require a special parser to read on demand, usually provided as a TileProvider by a plugin. The following community-maintained plugins are available to read these formats:

• MBTiles: flutter_map_mbtiles (vector_map_tiles_mbtiles when using vector tiles)

• PMTiles: flutter_map_pmtiles (vector_map_tiles_pmtiles when using vector tiles, also works in online contexts)

Uncontained

When uncontained, tiles are usually in a tree structure formed by directories, usually 'zoom/x/y.png'. These don't require special parsing, and can be provided directly to the TileLayer using one of the built-in local TileProviders.

AssetTileProvider

You can ship an entire tile tree as part of your application bundle, and register it as assets in 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.

FileTileProvider

This allows for more flexibility: you could store a tile tree on a remote server, then download the entire tree later to the device's filesystem, perhaps after intial setup, or just an area that the user has selected.

This means that the setup may be more complicated for users, and it introduces a potentially long-running blocking action, but the application's bundle size will be much smaller.

Then, the external controller controls the map, and you can access the MapCamera from outside of the map using MapController.camera. For example:

Pitfalls of an external controller

flutter_map wants to help keep map data available for everyone. One of the largest sources of this data is OpenStreetMap. OpenStreetMap data powers the majority of non-proprietary maps - from actual map tiles/images to navigation data - in existence today. The data itself is free for everyone under the ODbL.

The OpenStreetMap Foundation run OpenStreetMap as a not-for-profit. They also provide a public tile server at https://tile.openstreetmap.org, which is run on donations and volunteering time. This server is used throughout this documentation for code examples, and in our demo app, and is available at the following template URL:

The OpenStreetMap public tile server is without cost (for users), but, "without cost" ≠ "without restriction" ≠ "open".

What is flutter_map doing?

What has OSMF done?

Why?

The OpenStreetMap tile server is NOT free to use by everyone.

Data collected by OSM on 2025/06/09 shows flutter_map as the largest single user-agent in terms of the average number of tile requests made per second over the day. Whilst it is true that there are multiple user agents smaller who make up an overall much larger portion of total usage - for example, leaflet.js's usage is split across the browsers' user-agents, as is flutter_map usage on the web - the usage of flutter_map cannot be ignored.

The top 7 user-agents are shown below, in order (with traffic rounded to the nearest whole tile). ('Missed' tiles are those which required fresh rendering, and are more expensive than most other requests.)

And looking in more detail at the User-Agent's making up the primary 'flutter_map (*)' agent, on 2025/05/28:

We are extremely proud to see flutter_map being used so much! At the same time, we are aware that there are many users placing a potential strain on OpenStreetMap, which we want to minimize:

• We do not want to discourage legitimate use-cases from using the OpenStreetMap tile servers

• We want to help users who may be accidentally or unknowingly breaking the OpenStreetMap usage policies adjust their project so they can continue to benefit from cost-free tiles

• However, we do wish to discourage illegitimate use-cases or users who are intentionally breaking the OpenStreetMap usage policies

Therefore, we are introducing measures to force users to read the OpenStreetMap Tile Usage Policy before allowing them to use the servers in release builds:

• This is easy for legitimate users who have already read the policy and follow it

• It helps users accidentally breaking the policies to see why it's so important to follow them, and what they can do to fix any issues

• It adds friction for users intentionally breaking the policies

What should I do?

I have more questions

If you've got a question or comment regarding this new policy, or if you think we've missed something, please reach out to us on Discord (or via GitHub Discussions).

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.

Recommended Setup

Other Properties

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

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:

This policy may change at any time subject to the needs and constraints of the project. Commercial services, or those that seek donations, should be especially aware that access may be withdrawn at any point: you may no longer be able to serve your paying customers if access is withdrawn.

Also note all the other requirements, which may require you to make adjustments to your project...

There's also other options to implement Caching to meet the requirements, and go beyond the capabilities of the built-in caching.

To do this, set the flutter.flutter_map.unblockOSM environment variable when building/running/compiling. Use the dart-define flag to do this.

To evidence that you've read and understood the tile policy, you should set it to the exact string (excluding any surrounding whitespace, including all other punctuation) following the phrase from the policy:

OpenStreetMap data is free for everyone to use. _____

For example, to run the project:

You can also add this to your IDE's configuration to automatically pass this argument when running from your IDE. For example, in VS Code:

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

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.

From the filesystem (filesystem/dynamic offline)

1. Set the tileProvider to FileTileProvider()

2. Set the urlTemplate to the path to each tile within the filesystem, using the placeholders as necessary

3. Ensure the app has any necessary permissions to read from the filesystem

flutter_map (<packageName or 'unknown'>)

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.

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 Tile Providers for more information.

See Tile Providers for more information about tile providers generally.

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.