FlutterMap(
    mapController: MapController(),
    options: MapOptions(),
    children: [],
);

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

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

Since v8 & v8.2, flutter_map supports unbounded horizontal (longitudinally) scrolling for the default map projection. This means users can keep scrolling left and right (when North is up) and never hit an edge! Feature layers, such as the PolygonLayer, can also take advantage of this functionality.

Enabling/disabling unbounded horizontal scrolling

Within the codebase, unbounded horizontal scrolling is referred to as replicatesWorldLongitude, and is set on the CRS/projection level.

The default projection, Epsg3857, enables the functionality by default.

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.

Tracestrack has a wide variety of raster styles, including topographic and standard bases, in multiple different color schemes (light & dark). It also supports vector tiles, which makes it super flexible - use raster tiles now, and be ready to switch to vector tiles!

1. Use https://console.tracestrack.com/explorer to find your ideal style

2. Create an account

3. Copy the URL template from the result box at the bottom and paste it into your TileLayer

If you're looking for extremely low cost & often free (even for commercial usage), but still reliable, and low frills service, Lima Labs provides high quality raster tiles with one style based off the standard CARTO style.

1. Sign up for an account - Lima Labs operates manual verification, so you may have to wait a few days

2. Use the common URL (https://cdn.lima-labs.com/0/0/0.png?api=___) with your API key

Plugins extend flutter_map's functionality. There's no specific definition, but they often offer additional utilities and/or layers.

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

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 Plugins List. 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

• preferably includes the #flutter-map pub.dev topic

• is available via a standard pub.dev package installation

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

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.

class CustomMobileLayer extends StatelessWidget {
  const CustomMobileLayer({super.key});

  @override
  Widget build(BuildContext context) {    
    return MobileLayerTransformer(
      child: // your child here
    );
  }
}

class CustomStaticLayer extends StatelessWidget {
  const CustomStaticLayer({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox.expand();
    // and/or
    return Align();
  }
}

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.

Setting up a 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 under 30 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!

We think flutter_map hits the spot for many Flutter apps: . But don't just take it from us - check out who else is using flutter_map, and what they think of it!

These great projects all make use of flutter_map!

But there's more: check out the , and the #showcase channel for more projects on our Discord server.

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.

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.

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!

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.

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:

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

• Defines restrictions that last throughout the map's lifetime

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:

• Allow ONLY specified interactions, with the bitwise 'OR' (|) operator For example, InteractiveFlag.drag | InteractiveFlag.rotate, allows the map to ONLY be dragged or rotated (by the touchscreen), except any other options configured separately (such as keyboard options)

• Disable specified interactions, using the & and ~ operators For example, ~InteractiveFlag.rotate (which is equivalent to

For example, to disable flinging:

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:

Keyboard gestures can be configured through KeyboardOptions. By default, the map can be panned via the arrow keys. Additionally, panning using the WASD keys can be enabled, as well as rotation with Q & E, and zooming with R & F. All keys are physical and based on the QWERTY keyboard, so on other keyboards, the positions will be the same, not necessary the characters.

Leaping occurs when the trigger key is pressed momentarily instead of being held down. This can also be customized.

To define a Proj4Crs (custom CRS) you have to register a projection of proj4.Projection. For that you must import proj4dart library as follows:

You can create and register your custom projection in multiple ways, but the recommended is to use a Proj4 definition string from . For example for EPSG:3413 (WGS 84 / NSIDC Sea Ice Polar Stereographic North) you can find it . This is how a Proj4 definition string looks like:

With this Proj4 definition string and a string identifier register your proj4.Projection like this:

To display anything on the map, you'll need to include at least one layer. This is usually a , 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 , or any widget as your own custom layer ()!

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.

Most layers are 'mobile', such as the

A TileProvider works with a TileLayer to supply tiles (usually images) when given tile coordinates.

Tile providers may support compatible (including built-in caching), or may implement caching themselves.

Tiles are usually dynamically requested from the network/Internet, using the default NetworkTileProvider. Tiles can also come from the app's assets, the filesystem, a container/bundle, or any other source.

This tile provider uses the TileLayer.urlTemplate to get the appropriate tile from the a network, usually the Internet.

You can add single point features - including arbitrary widgets - to maps using MarkerLayer and Markers.

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.

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,
    ),
  ],
),

Interactivity

CircleLayers and CircleMarkers support hit detection and interactivity.

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

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

Rotation & Skewing

RotatedOverlayImage supports rotation and parallelogram skewing, by accepting 3 points instead of 2.

To calculate a rotation without skewing, given a center and a 3rd corner, see https://stackoverflow.com/a/78064659/11846040.

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.

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.

The behaviour of hit testing can be confusing at first. These rules define how hit testing usually behaves:

1. Gesture callbacks in MapOptions are always invoked, no matter what is within the layers or the result of hitTests in those layers, with the exception of custom defined hit test behaviours (not those layers that support interactivity, see Layer Interactivity), such as applying GestureDetectors around Marker.children

1. Hit testing is always* performed on interactive-capable layers (see ) even if they have not been set-up for interactivity: hit testing != interactivity

2. Non-interactable layers (such as ) have no defined hitTest, and behaviour is situation dependent

3. A successful hit test (true) from an interactable layer will prevent hit testing on layers below it in the children stack

To change this behaviour, make use of these three widgets, wrapping them around layers when and as necessary:

• TranslucentPointer: a general purpose 'widget' included with flutter_map that allows the child to hit test as normal, but also allows widgets beneath it to hit test as normal, both seperately

For example, a marker with a GestureDetector child that detects taps beneath a Polyline will not detect a tap, no matter if the PolylineLayer has a defined hitNotifier or the Polyline has a defined hitValue. A defined onTap callback in MapOptions would be called however. If the Marker were no longer obscured by the Polyline, it's onTap callback would be fired instead of the one defined in

However, this behaviour could be changed by wrapping the PolylineLayer with a TranslucentPointer. This would allow interacitivity to function as normal, but also allow the Marker beneath to have it's onTap callback fired. Further wrapping another TransclucentPointer around the MarkerLayer would allow all 3 detections to function.

To display map tiles from Google Maps, a little more effort is needed, as they require a complex session token system.

Therefore, we haven't yet constructed a full guide, so please read the Google Developers documentation for more info:

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.

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.

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.

Caching is extensible.

To create a new caching provider which is compatible with all tile providers which are compatible with built-in caching, create a class which implements MapCachingProvider and its required interface.

class CustomCachingProvider implements MapCachingProvider {
  @override
  bool get isSupported => throw UnimplementedError();

  @override
  Future<({Uint8List bytes, CachedMapTileMetadata metadata})?> getTile(
    String url,
  ) {
    throw UnimplementedError();
  }

  @override
  Future<void> putTile({
    required String url,
    required CachedMapTileMetadata metadata,
    Uint8List? bytes,
  }) {
    throw UnimplementedError();
  }
}

Compatible tile providers must check isSupported before using getTile or putTile.

Check in-code documentation for more detail on requirements and expectations.

Many providers may only work on certain platforms. In this case, implementations can mix-in DisabledMapCachingProvider on unsupported platforms:

If a provider cannot read a tile from the cache, but the tile is present, the provider should:

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

Thanks for considering donating to us: we're extremely grateful for all donations of any size!

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, whether that's through supporting external contributors through bounties, covering any unforeseen and future costs, or supporting the maintainers.

Donations allow us to keep flutter_map up-to-date and full of features that save you from expensive tile server fees and that make us Flutter's №1 non-commercially aimed map client.

Past Supporters

Check out our public past supporters on our GitHub Sponsors page. A huge thanks to all of them, they keep this project going!

And a huge thanks to all these people and organisations that supported us previously. In no particular order, thanks to:

• androidseb

• Roundtrip

• corepuncher

• Maxi

• V3ntus

• OCELL

• ishcherbina

• ... and everyone else who donated anonymously

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:

  • @johnpryan - the original founder of this project

  • @kengu

• The authors of this documentation:

  • @JaffaKetchup

• Anyone who has contributed to making flutter_map:

• Anyone who has made plugins for flutter_map:

• Anyone who has donated to flutter_map:

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

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.

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

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

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

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:

https://tile.openstreetmap.org/{z}/{x}/{y}.png

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

What should I do?

Here's some highlights since v8.0:

That's already a lot, but it's only scratching the surface. Alongside the community, we've improved our example app, , added even more customizability and fine-grained control - not even to mention the multiple bug fixes and other performance improvements.

Why not check out the CHANGELOG for the full list of curated changes, and the full commit and contributor listing if you like all the details:

The following layers support 'interactivity':

Depend on flutter_map from as normal! Use the command line or add the dependency manually to your pubspec.yaml.

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.

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.

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.

• Caching Automatically store tiles as the user loads them through interacting with the map, usually on a temporary basis

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

• Provide a set of pre-determined tiles to all users through app assets or the filesystem

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 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 for more info.

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

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 , 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:

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.

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:

• : (when using vector tiles)

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

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.

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.

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.

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,
        );
      },
    );
  }
}

flutter_map supports integration of basic map tile caching (with compatible tile providers) through caching providers & provides an automatically-enabled implementation on non-web platforms, known as built-in caching.

Caching aims to:

• Improve developer experience by:

  • Reducing the costs of using tile servers, by reducing duplicate tile requests

  • Keep your app lightweight - the built-in cache doesn't ship any binaries or databases, just a couple extra libraries you probably already use

• Improve user experience by:

  • Reducing tile loading durations, as fetching from the cache is very quick

  • Reducing network/Internet usage, which may be limited or metered/expensive (eg. mobile broadband)

• Improve compliance with tile server requirements, by reducing the strain on them

• Be extensible, customizable, and integrate with multiple tile providers

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

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:

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

You can also use any other MapCachingProvider implementation, such as provided by plugins, or ! 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.

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

You can add lines formed from coordinates to maps using PolylineLayer and Polylines.

Polylines support a solid, dotted, and dashed style, through a StrokePatternpassed as an argument toPolyline.pattern. These are flexible, and spacing and sizing may be customized.

You can add areas/shapes formed from coordinates to maps using PolygonLayer and Polygons.

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

Interactivity

PolygonLayers and Polygonss support hit detection and interactivity.

Multi-Worlds

The PolygonLayer paints its Polygons across all visible worlds by default. This can be changed.

Performance Optimizations

flutter_map includes many performance optimizations built in, especially as of v7. Some are enabled by default, but may be only 'weakly' applied, and others must be enabled manually. There are also some other actions that can be taken externally to improve performance

The following list is ordered from least 'intrusive'/extreme, to most intrusive. Remember to consider the potential risks of enabling an optimization before doing so.

The default renderer supports two painter fill methods using different Flutter APIs. These fill methods change the way Flutter decides what is considered within a polygon (and should be filled), and what is outside. This can change the way particularly intersections and overlaps appear visually.

This can be set using the painterFillMethod property and the PolygonPainterFillMethod enum.

Many apps will not need to change from the default method. Before changing the method, profile and test for visual glitches thouroughly.

Inverted filling (invertedFill) allows a color to be applied to all parts of the map outside a polygon. Transparently filled polygons will reveal the layers beneath without the inverted fill color.

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

In addition to the user interacting with the map, for example by using their cursor, trackpad, or touchscreen, the map can be controlled programmatically.

Programmatic interaction consists of two parts: reading and setting information about the map.

To use programmatic interaction, it's important to understand the difference between the map's 'camera' and the map's 'controller', and their relationship.

Camera

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:

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

For example:

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

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

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

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:

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.

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

Additional Layers

Offline Mapping

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

The base layer of most maps is a TileLayer, which displays square raster images in a 2D continuously-pannable grid, where each image is loaded as/just before it comes into view.

TileLayer(
  urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
  userAgentPackageName: /*'com.example.app'*/, // Add your app identifier
  // + many other options
),

Recommended Setup

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.

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: