Apply To Be Listed

Want to advertise your project here? For more information, and to apply, please see:

• The application form for non-OSS projects

• The application form for OSS and/or non-profit projects (it's free!)

Non-OSS Sponsors

OSS and/or Non-Profit Projects

Plugins

Support Us

Please consider donating anything you can to us, we're extremely grateful for any and all donations. They keep us going and will allow us to cover any unforeseen or future costs, and potentially open up more doors and opportunities in future!

We'll donate 15% of what we receive to the OpenStreetMap Foundation, as a thanks for their excellent work. The remainder goes directly to improving flutter_map.

Enter a nickname to be listed below in Past Supporters, and enter your Discord username to be granted the "Supporter" role on our server and gain access to a special supporter-only chat channel. These benefits last indefinitely (but may take 48 hours to grant, as this is done manually).

• Donate with GBP & British specific payment methods

• Donate with EUR & European specific payment methods

We support a variety of payment methods through Stripe, although some have lower fees for us. In general, cards have the highest fees, and the closer the method to the bank, the lower the fees. Donating in the GBP currency also reduces our fees, but we provide EUR checkout to add extra payment methods for those living in Europe. If paying in a currency other than your own, your bank's exchange rate/terms will apply. At this time, only one-time donations are accepted: please get in touch if you'd like to donate on a regular basis.

Past Supporters

Huge thanks to all our past supporters, you help keep this project going. In no particular order, thanks to:

• androidseb

• Roundtrip

• corepuncher

• Maxi

• ... and everyone else who donated anonymously

Feature Highlights

Demonstration

Setting up an interactive and compliant map is simpler than making your lunch-time coffee! It can be accomplished in just under 30 lines and a minute or two to install.

This code snippet demonstrates everything you need for a simple map (in just over 20 lines!), but of course, FM is capable of much more than just this, and you could find yourself lost in the many options available and possibilities opened!

import 'package:flutter_map/flutter_map.dart';
import 'package:latlong2/latlong.dart';

@override
Widget build(BuildContext context) {
  return FlutterMap(
    options: MapOptions(
      initialCenter: LatLng(51.509364, -0.128928),
      initialZoom: 9.2,
    ),
    children: [
      TileLayer(
        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
        userAgentPackageName: 'com.example.app',
      ),
      RichAttributionWidget(
        attributions: [
          TextSourceAttribution(
            'OpenStreetMap contributors',
            onTap: () => launchUrl(Uri.parse('https://openstreetmap.org/copyright')),
          ),
        ],
      ),
    ],
  );
}

Get Help

Not quite sure about something? No problem. Please get in touch via any of these methods, and we'll be with you as soon as possible. Please remember that we are volunteers, so we cannot guarantee (fast) support.

• For bug reports & feature requests: check the FAQs then GitHub Issues

• For support & everything else: check the FAQs then flutter_map Discord server

FAQs

We get quite a lot of similar questions, so please check if your question is here before you ask!

The MapCamera object describes the map's current viewport. It does not provide methods to change it: that is the responsibility of a MapController.

Usage Inside Of A FlutterMap Child

To get the camera from within the context of a FlutterMap widget, use MapCamera.of(context).

If this throws a StateError, try wrapping the concerned widget in a Builder, to ensure the FlutterMap widget is parenting the BuildContext. If this has no effect, use Usage Outside Of FlutterMap instead.

Usage Outside Of FlutterMap

Single Time

To get the camera from outside the context of the FlutterMap widget, you'll need to setup a MapController first: see Control Camera > Usage Outside Of FlutterMap.

Then, use the .camera getter.

Listen To Changes

To display anything on the map, you'll need to include at least one layer. This is usually a TileLayer, which displays the map tiles themselves: without it, the map isn't really a very good map!

To insert a layer, add it to the children property. Other layers (sometimes referred to as 'feature layers', as they are map features) can then be stacked on top, where the last widget in the children list is topmost. For example, you might display a MarkerLayer, or any widget as your own custom layer (Creating New Layers)!

Each layer is isolated from the other layers, and so handles its own independent logic and handling. However, they can access and modify the internal state of the map, as well as respond to changes.

Per-Layer Gesture Handling

By default, each layer acts translucently to gestures, meaning they can handle gestures themselves, but they also allow gestures to bubble down to other layers beneath them.

This behaviour can be disabled in the MapOptions, by setting .applyPointerTranslucencyToLayers false. Optionally, then, the TranslucentPointer widget can be wrapped around individal layers to achieve the desired effect.

Mobile vs Static Layers

Most layers are 'mobile', such as the TileLayer. These use a MobileLayerTransformer widget internally, which enables the layer to properly move and rotate with the map's current camera.

However, some layers are 'static', such as the AttributionLayers. These aren't designed to move nor rotate with the map, and usually make use of a widget like Align and/or SizedBox.expand to achieve this.

Both of these layer types are defined in the same children list. Most of the time, static layers go atop mobile layers, so should be at the end of the list.

flutter_map provides an example application showcasing much of its functionality. In some cases, the example app contains undocumented functionality, so it's definitely worth checking out!

Live Web Demo

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.

You can add circle areas to maps by making them out of a center coordinate and radius using CircleLayer and CircleMarkers.

CircleLayer(
  circles: [
    CircleMarker(
      point: LatLng(51.50739215592943, -0.127709825533512),
      radius: 10000,
      useRadiusInMeter: true,
    ),
  ],
),

You can add areas/shapes to maps by making them out of individual coordinates using PolygonLayer and Polygons.

PolygonLayer(
  polygons: [
    Polygon(
      points: [LatLng(30, 40), LatLng(20, 50), LatLng(25, 45)],
      color: Colors.blue,
      isFilled: true,
    ),
  ],
),

Polygon Manipulation

'flutter_map' doesn't provide any public methods to manipulate polygons, as these would be deemed out of scope.

However, some useful methods can be found in libraries such as 'latlong2' and 'poly_bool_dart'. These can be applied to the input of Polygon's points argument, and the map will do it's best to try to render them. However, more complex polygons - such as those with holes - may be painted inaccurately, and may therefore require manual adjustment (of holePointsList, for example).

onTap Support

flutter_map supports WMS tile servers through WMSTileLayerOptions - wmsOptions in TileLayers.

For usage, please refer to the Full API Reference, and the examples in the example app.

You can add single point features - such as pins, labels, or markers - to maps using MarkerLayer and Markers.

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.

To control the map (such as moving it to a new position and zoom level), you'll need a MapController. The controller does not provide access to the current viewport/camera: that is the responsibility of .

Usage Inside Of A FlutterMap Child

To control the map from within the context of a FlutterMap widget, use MapController.of(context).

If this throws a StateError, try wrapping the concerned widget in a Builder, to ensure the FlutterMap widget is parenting the BuildContext. If this has no effect, use instead.

Usage Outside Of FlutterMap

Initialisation

To use a MapController, it must initialised like any other object and then passed to the FlutterMap. This attaches them until the map is disposed.

Usage Inside initState()

Sometimes, it is necessary MapController in initState() before the map has been built, for example to attach an event listener (). This is not directly possible, as the map must be built for the controller to be attached.

Instead, use the MapOptions.onMapReady callback. The initialised MapController can be used freely within it.

Animated Movements

Whilst animated movements through MapControllers aren't built-in, the provides this, and much more!

The example application also includes a page demonstrating a custom animated map movement without the plugin.

Start by adding some to children, then configure the map in . Additionally, if required, add a MapController: .

Placement Recommendations

It is recommended to make the map as large as possible, to allow it to display a lot of useful information easily.

As such, we recommend using a depth-based layout (eg. using Stacks) instead of a flat-based layout (eg. using Columns). The following 3rd party packages might help with creating a modern design:

If you must restrict the widget's size, you won't find a height or width property. Instead, use a SizedBox or Column/Row & Expanded.

Keep Alive

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 .

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.

There are 2 main types of tiles a server can serve: raster and vector; each has their own advantages and drawbacks. This page is designed to help you choose a type for your app, and help you use vector tiles if you choose to.

Raster Tiles

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 to do this.

Thunderforest is a popular tiered-payment (with free tier) tile provider solution, especially for generic mapping applications. Note that using 'flutter_map' uses up your 'Map Tiles API' requests.

Install

From pub.dev

Just import the package as you would normally, from the command line:

flutter pub add flutter_map latlong2
flutter pub add flutter_map_cancellable_tile_provider # OPTIONAL

From github.com

If you urgently need the latest version, a specific branch, or a specific fork, you can use this method.

First, use From pub.dev, then add the following lines to your pubspec.yaml file, as a root object:

dependency_overrides:
    flutter_map:
        git:
            url: https://github.com/fleaflet/flutter_map.git
            # ref: main (custom branch/commit)

Additional Setup

Web

Always force usage of the CanvasKit renderer instead of the HTML renderer, even on mobile devices.

The HTML renderer causes performance issues, and may also cause other bugs. Although the CanvasKit renderer does require slightly more Javascript (and therefore a longer download time), it works much better with flutter_map.

For more information about web renderers, see https://docs.flutter.dev/platform-integration/web/renderers.

Android

flutter_map needs to access the Internet to load tiles, in most cases. On Android, apps must include the INTERNET permission in their manifest. Add the following line to all manifests:

<uses-permission android:name="android.permission.INTERNET"/>

MacOS

flutter_map needs to access the Internet to load tiles, in most cases. On MacOS, apps must include a dedicated entitlement. Add the following lines to 'macos/Runner/DebugProfile.entitlements' and 'macos/Runner/Release.entitlements':

<key>com.apple.security.network.client</key>
<true/>

Import

After installing the package, import it into the necessary files in your project:

import 'package:flutter_map/flutter_map.dart';
import 'package:latlong2/latlong.dart';

When changes happen to FlutterMap's internal state (such as a change to the current MapCamera) it emits a MapEvent, which can be handled by you.

Catching All Events

There's two methods to catch all emitted MapEvents. These methods expose the raw MapEvent, and is recommended in cases where multiple events need to be caught, or there's no more specific callback method available in MapOptions (see Catching Specific Events).

• Listening to a MapController's mapEventStream, which exposes events via a Stream

• Specifying a callback method in MapOptions.onMapEvent

Catching Specific Events

If only a couple of events need to be caught, such as just an onTap handler, it is possible to avoid handling the raw Stream of MapEvents. Instead, MapOptions has callbacks available for the following events:

• onTap

• onLongPress

• onPositionChanged

• onPointerDown/onPointerUp/onPointerHover/onPointerCancel

• onMapReady Primarily used for advanced MapController Usage Inside initState()

options: MapOptions(
    interactiveFlags: ~InteractiveFlag.doubleTapZoom,
),

Credits

Huge thanks to everyone who uses, supports, and/or contributes to flutter_map in any way, you've helped make the most popular non-commercially aimed mapping solution for Flutter!

In particular, thanks go to:

• All the current maintainers:

  • @ibrierley

  • @JaffaKetchup

  • @mootw (previously @MooNag)

  • @TesteurManiak

  • @josxha

• All the previous maintainers:

  • John P Ryan - the original founder of this project, over at AppTree Software

  • @kengu

  • @maRci002

• The authors of this documentation:

  • @JaffaKetchup

• Anyone who has contributed to making flutter_map: Contributor List

• Anyone who has made plugins for flutter_map: Plugins List

• Anyone who has donated to flutter_map: Past Supporters

Contributing

We're always happy to receive improvements and fixes, so please submit them whenever you can! A few key points are listed below.

• If your PR will add a major or breaking change, please discuss it with us first, via the Issue Tracker We don't want to waste your time if we think it's more appropriate for a plugin, and it helps to make a clear plan before starting work

• Create a draft PR as soon as work starts, and take it out of draft status when ready for review Keep everyone in the loop, so no-one tries working on the same thing as you

• Don't change the package version, GitHub workflows, lints, or any other meta files without clarification We rely on a standardized process and procedure to ensure top-quality releases

• Use a clear (preferably Conventional) PR title This makes it easier for us to group commits for release and write correct CHANGELOGs

Apply To Be A Maintainer

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.

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

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

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.

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.

Creating a new map layer is a great way to achieve a more custom, performant, map design. For example, it might be used to display a scale bar, or overlay a grid.

1. Creating A Layer Widget

It starts with a normal StatelessWidget or StatefulWidget, which then starts its widget tree with a widget dependent on whether the layer is designed to be either 'mobile' or 'static', depending on the purpose of the layer. For more information, see Mobile vs Static Layers.

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.

final camera = MapCamera.of(context);
final controller = MapController.of(context);
final options = MapOptions.of(context);

Before publishing your app to users, you should credit any sources you use, according to their Terms of Service.

There are two built in methods to provide attribution, RichAttributionWidget and SimpleAttributionWidget, but you can also build your own using a simple Align widget.

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.

children: [
  RichAttributionWidget(
    animationConfig: const ScaleRAWA(), // Or `FadeRAWA` as is default
    attributions: [
      TextSourceAttribution(
        'OpenStreetMap contributors',
        onTap: () => launchUrl(Uri.parse('https://openstreetmap.org/copyright')),
      ),
    ],
  ),
],

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.

children: [
  SimpleAttributionWidget(
    source: Text('OpenStreetMap contributors'),
  ),
],

If one of the doesn't suit your needs, then you can create your own, to achieve maximum customizability.

Most plugins create either new , or new . Some plugins just provide additional useful tools.

Submitting A New Plugin

If you've made your own plugin that you're willing to share, please let us know in the #plugins channel on the flutter_map Discord server. We can then add it to the . We're always looking forward to see what you've made!

When submitting a plugin, please ensure the plugin:

• preferably includes 'flutter_map_' in the name, by convention

• is preferably available via a standard pub.dev package installation

• includes good documentation (at least to setup basic functionality), and a code example

Layers

Interactive maps are often formed from multiple layers of data, which can be panned (moved), rotated, and sometimes tilted/pitched, based on the user's gesture input, or another programmatic control.

Tile Basics

One type of layer included on every map is known as a tile layer, which displays tiles, square segments of a map.

When multiple tiles, which are each the same dimensions, are laid out around each other, they give the illusion of one continuous map.

Tiles can be referenced/identified in a few different ways, such as:

• Slippy Map Convention (the most popular/common)

• (very similar to the Slippy Map Convention)

Tiles themselves can be of two types:

• Raster Each tile is a normal pre-rendered standard image, such as JPG or PNG

• Vector Each tile is a special format containing the data for the tile, and is then rendered by the end library

This library/documentation focuses on maps accessible via the Slippy Map Convention, although all are supported.

This library only supports raster tiles. See for more information.

Slippy Map Convention

Slippy map tiles are accessed by 3 coordinates, x/y/z.

X & Y coordinates correspond to all the latitudes and longitudes contained within that tile, however they are not actual longitude and latitude. For example, geographic coordinate (61.127, -0.123) might be in the tile (128983, 430239).

The Z value represents the current zoom level, where one tile () covers the entire planet with extremely low detail at level 0, to level 20 (although some tile servers will support even higher zoom levels) where over 1 trillion tiles are required to cover the entire surface of the Earth.

Sourcing Tiles

Tiles, especially raster tiles, take a lot of computing power and time to generate, because of the massive scale of all the input and output data. Therefore, most tiles are sourced externally, from an online tile server (either publicly or by users holding an API key), or sometimes from the local filesystem or asset store of the app.

Tile Providers

A tile provider (within flutter_map) is responsible for:

• Constructing the path/URL to a tile, when given its coordinates (x/y/z):

• Using an ImageProvider or other mechanism to fetch that tile:

• Performing any other processing steps, such as caching

But don't worry! flutter_map (or a plugin) creates a provider for you, so for most use cases and tile sources, you shouldn't need to handle this yourself!

Using maps without an Internet connection is common requirement. Luckily, there are a few options available to you to implement offline mapping in your app.

• Automatically store tiles as the user loads them through interacting with the map

• Download an entire area/region of tiles in one shot, ready for a known no-Internet situation

• Provide a set of tiles to all users through assets or the filesystem

Caching

There's 3 methods that basic caching can be implemented in your app, two of which rely on community maintained plugins:

1. (lightweight and MIT licensed)

2. (also includes , but GPL licensed)

3. Custom implementation, via a and ImageProvider (either custom or via a package such as )

Bulk Downloading

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

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

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 to convert it to the correct structure first. Alternatively, you can use an external package such as '' to extract during runtime.

One common requirement is a custom TileProvider, and potentially a custom ImageProvider inside. This will allow your plugin to intercept all tile requests made by a map, and take your own action(s), before finally returning a tile.

1. Extending TileProvider

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.

class CustomTileProvider extends TileProvider {
    CustomTileProvider({
        // Suitably initialise your own custom properties
        super.headers, // Accept a `Map` of custom HTTP headers
    })
}

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.

    @override
    bool get supportsCancelLoading => true;
    
    @override
    ImageProvider getImageWithCancelLoadingSupport(
        TileCoordinates coordinates,
        TileLayer options,
        Future<void> cancelLoading,
    ) =>
        CustomCancellableImageProvider(
            url: getTileUrl(coordinates, options),
            fallbackUrl: getTileFallbackUrl(coordinates, options),
            cancelLoading: cancelLoading,
            tileProvider: this,
        );

    @override
    ImageProvider getImage(TileCoordinates coordinates, TileLayer options) =>
        CustomImageProvider(
            url: getTileUrl(coordinates, options),
            fallbackUrl: getTileFallbackUrl(coordinates, options),
            tileProvider: this,
        );

(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

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

This has a default of NetworkTileProvider which gets tiles from the internet through a dedicated image provider.

There's two situations in which you'll need to change the tile provider:

• Sourcing tiles from the filesystem or asset store: Local Tile Providers

• Using a plugin that instructs you to do so (Creating New Tile Providers)

Network Tile Providers

These tile providers use the urlTemplate to get the appropriate tile from the a network, usually the World Wide Web.

The underlying custom ImageProviders will cache tiles in memory, so that they do not require another request to the tile server if they are pruned then re-loaded. This should result in them being loaded quicker, as well as enabling already loaded tiles to appear even without Internet connection (at least in the same session).

NetworkTileProvider

This is the default tile provider, and does nothing particularly special. It takes two arguments, but you'll usually never need to specify them:

• httpClient: BaseClient By default, a RetryClient backed by a standard Client is used

• headers: Map<String, String> By default, only headers sent by the platform are included with each request, plus an overridden (where possible) 'User-Agent' header based on the userAgentPackageName property

CancellableNetworkTileProvider

Tiles that are removed/pruned before they are fully loaded do not need to complete (down)loading, and therefore do not need to complete the HTTP interaction. Cancelling these unnecessary tile requests early could:

• Reduce tile loading durations (particularly on the web)

• Reduce users' (cellular) data and cache space consumption

• Reduce costly tile requests to tile servers*

• Improve performance by reducing CPU and IO work

This provider uses 'dio', which supports aborting unnecessary HTTP requests in-flight, after they have already been sent.

Although HTTP request abortion is supported on all platforms, it is especially useful on the web - and therefore recommended for web apps. This is because the web platform has a limited number of simulatous HTTP requests, and so closing the requests allows new requests to be made for new tiles. On other platforms, the other benefits may still occur, but may not be as visible as on the web.

Once HTTP request abortion is added to Dart's 'native' 'http' package (which already has a PR opened), NetworkTileProvider will be updated to take advantage of it, replacing and deprecating this provider. This tile provider is currently a separate package and not the default due to the reliance on the additional Dio dependency.

Local Tile Providers

These tile providers use the urlTemplate 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

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.

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

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:

• {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.

Retina Mode

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

Raster map tiles can look pixelated (especially on high density displays), so some servers support high-resolution "@2x" tiles, which are tiles at twice the resolution of normal tiles. However, not all tile servers support this, so flutter_map can simulate retina behaviour.

It is recommended to enable retina mode on high density displays (especially where the server natively supports retina tiles). This can be done by calling RetinaMode.isHighDensity with the current BuildContext, and passing the result to TileLayer.retinaMode.

If the {r} placeholder is present in the the urlTemplate, and retinaMode is enabled, then it will be filled with "@2x". If it is not present, but retinaMode is enabled, then flutter_map will simulate retina behaviour by requesting four tiles at a larger zoom level and combining them together in place of one.

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.

You can add lines to maps by making them out of individual coordinates using PolylineLayer and Polylines.

Performance Recommendations

Excessive use of polylines may create performance issues. There are two options to attempt to improve performance.

Sticking With PolylineLayer

It is easiest to try to squeeze as much performance out of Polylines as possible. However, this may not always be the best option.

Consider using both of the methods below:

• Split long lines into individual Polylines at regular intervals, then enable polylineCulling, in order to prevent the calculation and rendering of Polylines outside of the current viewport.

• Simplify the polyline by reducing the number of points within it, in order to reduce raster and calculation times. It is recommended to do this to varying degrees and resolutions based on the current zoom level. It may be possible to use an external Flutter library called .

The first method will improve performance when zoomed in, as more Polylines will be able to be culled, whilst the second method will improve performance when zoomed out, without impacting visuals (when done well).

Using A Separate TileLayer

If using PolylineLayer as above still does not reach satisfactory performance, then the best option may be to render a custom tile set. For example, this may be necessary when attempting to draw a number of long-distance routes, or other widespread dataset.

The first step is to render the desired lines into a tileset with a transparent background - is commonly used to do this, and generates vector-format MBTiles.

If you have raster tiles, you're all set to serve as normal/as you choose. More commonly though, you'll have vector tiles at this step, as with 'tippecanoe', so you'll need to do one of the following things:

• Try to convert it to raster tiles all in one shot, and if necessary, use a tool like to extract the raster .mbtiles into a slippy map tree

• Give the MBTiles/vector tiles to the vector map plugin

• Serve the tiles via something like , which provides an on-the-fly rasterizer

If you have raster tiles, you're all set to serve as normal.

To provide the tiles to the users within flutter_map, see .

Routing/Navigation

Routing is out of scope for 'flutter_map'. However, if you can get a list of coordinates from a 3rd party, then you can use polylines to show them!

Good open source options that can be self-hosted include (which includes a public demo server) and . You can also use a commercial solution such as Mapbox or Google Maps - these can often give more accurate/preferable results because they can use their traffic data when routing.

Converting Formats

You may have a polyline with 'Google Polyline Encoding' (which is a lossy compression algorithm to convert coordinates into a string and back). These are often returned from routing engines, for example. In this case, you'll need to decode the polyline to the correct format first, before you can use it in a Polyline's points argument.

One way to accomplish this is to use another Flutter library called , together with a custom method. You can use the code snippet below, which can just be pasted into a file and imported whenever needed:

You can then use the package and the above snippet by doing:

There are many independently maintained 'plugins' created by the 'flutter_map' community that give extra, prebuilt functionality, saving you even more time and potentially money.

Some pages in this documentation provide direct links to these plugins to make it easier for you to find a suitable plugin.

However, if you're just browsing, a full list is provided below (in no particular order), containing many of the available plugins. You can click on any of the tiles to visit its GitHub repo or pub.dev package.

Tools

External

These are not necessarily purpose built for flutter_map, but could be very useful for some applications for related purposes.

Additional Layers

Offline Mapping

To help choose between one of these plugins or a DIY solution, see:

Better Markers

Marker Clustering

Better Polylines & Polygons

Other Servers

There are plenty of other tile servers you can choose from, free or paid. Most provide a static tile service/API, usually called Static Tiles or just Tile Requests (if no vector tiles are supported).

If you're responsible for a tile server, and want to have your tile server and setup instructions listed in this documentation, please get in touch!

A good catalogue of servers (usually called Providers elsewhere) can be found at the websites below:

Serving Your Own Tiles

Switch2OSM also provides detailed instructions on how to serve your own tiles: this can be surprisingly economical and enjoyable if you don't mind a few hours in a Linux console.

However, this will require a very high-spec computer, especially for larger areas, and hosting this might be more complicated than it's worth. It's very difficult to fully understand the technologies involved.

To display their map tiles, Stadia Maps usually provides a 'Static Maps Base URL' for map styles. However, to integrate with 3rd-party APIs, they also provide a 'Raster XYZ PNGs URL' , and tiles requested through this endpoint consume 'Styled Raster Map Tiles' credits. This URL needs no extra configuration to integrate with flutter_map.

Retina tiles (high-DPI) tiles are available. Use the URLs containing '@2x' instead of '{r}'. The maximum zoom level that Stadia Maps supports is 20, so it is recommended to set maxNativeZoom or maxZoom as such.

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.

There are major breaking changes for all users, as well as some things users should check and possibly change.

Some changes have deprecations and messages, some do not. Please refer to the sections below for information on how to migrate your project, as well as in-code documentation and deprecation messages, if your migration is not listed below. Some changes are omitted if they are deemed unlikely to affect implementations.

Changelog & Highlights

There's loads of changes in this release, which will improve performance and reduce costs! Check out these highlights, along with the full changelog:

Migration Instructions

General/Misc

State Management

Children/Layers

Tile Layer

Marker Layer

Map Options

Tile Providers

To dictate & restrict what the map can and should do, regardless of its contents, it needs some guidance!

It provides options that can be categorized into three main parts:

• Initial positioning Defines the location of the map when it is first loaded

• Permanent rules Defines restrictions that last throughout the map's lifetime

• Event handling Defines methods that are called on specific map events

Initial Positioning

One part of MapOptions responsibilities is to define how the map should be positioned when first loaded. There's two ways to do this (that are incompatible):

• initialCenter (LatLng) & initialZoom

• initialCameraFit

  • by bounds (circumscribed): CameraFit.bounds

  • by bounds (inscribed): CameraFit.insideBounds

  • by coordinates (circumscribed): CameraFit.coordinates

It is possible to also set the map's initialRotation in degrees, if you don't want it North (0°) facing initially.

If rotation is enabled/allowed, if using initialCameraFit, prefer defining it by coordinates for a more intended/tight fit.

Permanent Rules

One part of MapOptions responsibilities is to define the restrictions and limitations of the map and what users can/cannot do with it.

Some of the options are described elsewhere in this documentation, in context. In addition, the API docs show all the available options, and below is a partial list of options:

• cameraConstraint

  • camera bounds inside bounds: CameraConstraint.bounds

  • camera center inside bounds: CameraConstraint.center

  • unconstrained (default): CameraConstraint.unconstrained

• maxZoom and minZoom Sets a hard limit on the maximum and minimum amounts that the map can be zoomed

• interactionOptions Configures the gestures that the user can use to interact with the map - for example, disable rotation or configure cursor/keyboard rotation

To display map tiles from Bing Maps, a little more effort is needed, as they use a RESTful API with quadkeys, rather than the standard slippy map system.

Luckily, we've constructed all the code you should need below! Feel free to copy and paste into your projects.

// All compatible imagery sets
enum BingMapsImagerySet {
  road('RoadOnDemand', zoomBounds: (min: 0, max: 21)),
  aerial('Aerial', zoomBounds: (min: 0, max: 20)),
  aerialLabels('AerialWithLabelsOnDemand', zoomBounds: (min: 0, max: 20)),
  canvasDark('CanvasDark', zoomBounds: (min: 0, max: 21)),
  canvasLight('CanvasLight', zoomBounds: (min: 0, max: 21)),
  canvasGray('CanvasGray', zoomBounds: (min: 0, max: 21)),
  ordnanceSurvey('OrdnanceSurvey', zoomBounds: (min: 12, max: 17));

  final String urlValue;
  final ({int min, int max}) zoomBounds;

  const BingMapsImagerySet(this.urlValue, {required this.zoomBounds});
}

// Custom tile provider that contains the quadkeys logic
// Note that you can also extend from the CancellableNetworkTileProvider
class BingMapsTileProvider extends NetworkTileProvider {
  BingMapsTileProvider({super.headers});

  String _getQuadKey(int x, int y, int z) {
    final quadKey = StringBuffer();
    for (int i = z; i > 0; i--) {
      int digit = 0;
      final int mask = 1 << (i - 1);
      if ((x & mask) != 0) digit++;
      if ((y & mask) != 0) digit += 2;
      quadKey.write(digit);
    }
    return quadKey.toString();
  }

  @override
  Map<String, String> generateReplacementMap(
    String urlTemplate,
    TileCoordinates coordinates,
    TileLayer options,
  ) =>
      super.generateReplacementMap(urlTemplate, coordinates, options)
        ..addAll(
          {
            'culture': 'en-GB', // Or your culture value of choice
            'subdomain': options.subdomains[
                (coordinates.x + coordinates.y) % options.subdomains.length],
            'quadkey': _getQuadKey(coordinates.x, coordinates.y, coordinates.z),
          },
        );
}

// Custom `TileLayer` wrapper that can be inserted into a `FlutterMap`
class BingMapsTileLayer extends StatelessWidget {
  const BingMapsTileLayer({
    super.key,
    required this.apiKey,
    required this.imagerySet,
  });

  final String apiKey;
  final BingMapsImagerySet imagerySet;

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: http.get(
        Uri.parse(
          'http://dev.virtualearth.net/REST/V1/Imagery/Metadata/${imagerySet.urlValue}?output=json&include=ImageryProviders&key=$apiKey',
        ),
      ),
      builder: (context, response) {
        if (response.data == null) return const Placeholder();

        return TileLayer(
          urlTemplate: (((((jsonDecode(response.data!.body)
                          as Map<String, dynamic>)['resourceSets']
                      as List<dynamic>)[0] as Map<String, dynamic>)['resources']
                  as List<dynamic>)[0] as Map<String, dynamic>)['imageUrl']
              as String,
          tileProvider: BingMapsTileProvider(),
          subdomains: const ['t0', 't1', 't2', 't3'],
          minNativeZoom: imagerySet.zoomBounds.min,
          maxNativeZoom: imagerySet.zoomBounds.max,
        );
      },
    );
  }
}

The InteractionOptions object passed to MapOptions.interactiveOptions configures the gestures that the user can use to interact with the map. For example, disable rotation or configure cursor/keyboard rotation.

Flags

flags is a bitfield that enables and disables the vast majority of gestures. Although technically the type is of int, it is usually set with a combination of InteractiveFlags.

By default, all gestures are enabled, but a non-interactive map can be created using none (and other options in addition).

Otherwise, to set flags, there's two methods:

• Add flags, with the bitwise 'OR' (|) operator in-between For example, InteractiveFlag.drag | InteractiveFlag.rotate

• Remove flags from all, using the & and ~ operators in-between For example, InteractiveFlag.all & ~InteractiveFlag.rotate

Cursor/Keyboard Rotation

Cursor/keyboard rotation is designed for desktop platforms, and allows the cursor to be used to set the rotation of the map whilst a (customizable) keyboard key (by default, any of the 'Control' keys) is held down.

The CursorKeyboardRotationOptions object passed to the property with the corresponding name configures this behaviour. The CursorKeyboardRotationOptions.disabled() constructor can be used to disable cursor/keyboard rotation.

There's many customization options, see the API docs for more information:

"Win" Gestures

You can overlay images on the map (for example, town or floor plans) using OverlayImageLayer and OverlayImages or RotatedOverlayImages.

OverlayImageLayer(
  overlayImages: [
    OverlayImage(
      bounds: LatLngBounds(
        LatLng(45.3367881884556, 14.159452282322459),
        LatLng(45.264129635422826, 14.252585831779033),
      ),
      imageProvider: NetworkImage(),
    ),
  ],
),

There's two ways to interact with the map - that is to control it, as well as receive data from it - and it's current viewport, aka. 'camera'.

via User Gestures

The first way is through user interaction, where they perform gestures (such as drags/pans), and the map reacts automatically to those gestures to change the camera view of the map.

These are usually restricted by Options. It is possible to disable all input, either by disabling all gestures, or by wrapping the map with something like IgnorePointer.

via Programmatic Means

When using programmatic means, there's two methods to most things, dependent on whether the context is within a FlutterMap (ie. usually a layer) or not.

If within FlutterMap's context, the methods usually cause automatic rebuilding. As well as the pages below, also see Creating New Layers.