Why choose flutter_map?

Code Demo

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

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), // Center the map over London
      initialZoom: 9.2,
    ),
    children: [
      TileLayer( // Bring your own tiles
        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png', // For demonstration only
        userAgentPackageName: 'com.example.app', // Add your app identifier
        // And many more recommended properties!
      ),
      RichAttributionWidget( // Include a stylish prebuilt attribution widget that meets all requirments
        attributions: [
          TextSourceAttribution(
            'OpenStreetMap contributors',
            onTap: () => launchUrl(Uri.parse('https://openstreetmap.org/copyright')), // (external)
          ),
          // Also add images...
        ],
      ),
    ],
  );
}

Get Help

Not quite sure about something? No worries, we're here to help!

• Check the FAQs below, and double check the documentation

• Then, for bug reports & feature requests: check for previous issues, then ask in GitHub Issues

• Then, for support & everything else: ask in flutter_map Discord server or GitHub Discussions

FAQs

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

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

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.

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.

See the code demo on the landing page to see how easy it is and how it all fits together in code, and see what's possible in our example app.

Install

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

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

Additional Setup

Web

Wasm/Renderer

CORS

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:

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

Import

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

Community Studies

Project Showcase

These great projects all make use of flutter_map!

Non-OSS Sponsors

OSS and/or Non-Profit Projects

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.

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.

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.

Layers With Elements

Some layers - such as PolygonLayer - take 'elements' - such as Polygons - as an argument, which are then displayed by the layer. They are usually displayed bottom-to-top in the order of the list (like a Stack).

Hit Testing & Interactivity

Some layers that use elements also support interactivity via hit testing. This is described in more detail on another page:

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

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:

Keyboard Gestures

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.

"Win" Gestures

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: Controllers & Cameras.

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:

• https://pub.dev/packages/backdrop

• https://pub.dev/packages/sliding_up_panel

• https://pub.dev/packages/material_floating_search_bar_2

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

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

Custom CRS

FM does have some support for using alternative CRSs.

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 Interation

However, the map camera can also be controlled by calling methods on a controller, and its state read by getting values from an exposed camera.

For more information, see:

For more information about what a MapController is, and when it is necessary to set one up in this way, see:

Basic Setup

The FlutterMap.controller parameter takes an externally intialised MapController instance, and attaches it to the map.

Usage Before Attachment (eg. Within initState)

It is not safe to assume that the MapController is ready to use as soon as an instance has been initialised, for example within initState.

It must first be attached to the FlutterMap, which could take up to multiple frames to occur (similar to the way a ScrollController is attached to a scrollable view). It helps to avoid errors by thinking of the controller in this way.

Instead, use the MapOptions.onMapReady callback. At this point, it is guaranteed that the controller will have been attached. You could also use this method to complete a Completer (and await its Future elsewhere) if you need to use it elsewhere.

Usage Within A State System/Model

Instead, some extra care should be taken, which may feel a little backwards at first. The state model should be used AFTER the normal setup.

2. In your state model, create a nullable (and initially uninitialised) MapController containing field

It may then be beneficial to unset the state model field when the controller is disposed: it should be disposed when the FlutterMap is disposed, which should occur just before the widget building the FlutterMap is disposed. Therefore, you can override the dispose method.

Animation

Projection

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

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

Coordinate Reference System (CRS)

You can use your previously registered proj4.Projection to create a custom CRS of type Proj4Crs. You can use the following parameters:

• <String> code (required): string identifier for the selected CRS, e.g. EPSG:3413

• <proj4.Projection> proj4Projection (required): the proj4.Projection object you wish to use

• <Bounds> bounds: bounds of the CRS in projected coordinates

• <List<double>> resolutions: an array of zoom factors (projection units per pixel, eg. meters/pixel)

• <List<double>> scales: scale factors (pixels per projection unit); specify either scales or resolutions, but not both!

• <List<Point>> origins: tile origin in projected coordinates (for TileLayer). Why is it needed? GeoServer by default can define different origins (top left coordinates) for each zoom levels. In case of origin mismatch the tile will be drawn on the wrong place: the map will jump at such zoom levels. If your origins vary with zoom levels the number of origins must match the number of resolutions. You can get the desired origins from a GetCapabilities WMTS call from geoserver e.g. http://[ip:port]/geoserver/gwc/service/wmts?request=GetCapabilities. This results an XML, and you have to look up for the TopLeftCorners for each TileMatrix of your TileMatrixSet.

• <Transformation> transformation: the transformation to use when transforming projected coordinates into pixel coordinates

An example:

Usage

Proj4Crs has multiple uses:

• Set FlutterMap's default CRS:
• Set a WMS layer's CRS

For complete code (with point transformation from one projection to another) see the page source code. This is how it looks like:

flutter_map makes use of InheritedModel to share 3 'aspects' with its built children:

• MapController: use to programatically control the map camera & access some helper functionality - control camera

• MapCamera: use to read the current state/position of the map camera & access some helper functionality that depends on the camera (such as latlngToPoint) - read camera

Accessing Aspects Within Descendants

All 3 aspects can be retrieved from within the context of a FlutterMap, which all built descendants should have access to. This usually means from within a layer: anywhere where there is at least one 'visible' builder method between the FlutterMap and the invocation.

Use the static of (or null-safe maybeOf) method to access the inherited aspect. For example, to access the MapCamera:

Accessing Aspects Elsewhere

MapCamera

Then use the camera getter on the MapController instance.

MapController

For more information about correctly setting up an external(ly accessible) MapController, see:

MapOptions

The basis of any map is a TileLayer, which displays square raster images in a continuous grid, sourced from the Internet or a local file system.

Recommended Setup

Other Properties

panBuffer

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

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

Tile Update Transformers

A TileUpdateTransformer restricts and limits TileUpdateEvents (which are emitted 'by' MapEvents), which cause tiles to update.

For example, a transformer can delay (throttle or debounce) updates through one of the built-in transformers, or pause updates during an animation, or force updates even when a MapEvent wasn't emitted.

For more information, see:

The following layers are interactable - they have specialised hitTesters and support external hit detection:

• Polyline Layer

• Polygon Layer

• Circle Layer

These all follow roughly the same pattern to setup hit detection/interactivity, and there's three or four easy steps to setting it up.

1. Attach A Hit Notifier

Pass a LayerHitNotifier to the hitNotifier parameter of the layer. The LayerHitNotifier should be created as a ValueNotifier defaulting to null, but strongly typed to LayerHitNotifier.

This notifier will be notified whenever a hit test occurs on the layer, with a LayerHitResult when an element (such as a Polyline or Polygon) within the layer is hit, and with null when an element is not hit (but the layer is).

final LayerHitNotifier hitNotifier = ValueNotifier(null);

// Inside the map build...
PolylineLayer( // Or any other supported layer
  hitNotifier: hitNotifier,
  polylines: [], // Or any other supported elements
);

It is possible to listen to the notifier directly with addListener, if you want to handle all hit events (including, for example, hover events). However, most use cases just need to handle particular gestures (such as taps). This can be done with a wrapper widget to 'filter' the events appropriately: 3. Gesture Detection.

2. Add hitValue To Elements

To identify which particular element was hit (which will be useful when handling the hit events in later steps), supported elements have a hitValue property.

This can be set to any object, but if one layer contains all the same type, type casting can be avoided (if the type is also specified in the LayerHitNotifier's type argument).

3. Gesture Detection

To only handle certain hits based on the type of gesture the user performed (such as a tap), wrap the layer with a gesture/hit responsive widget, such as GestureDetector or MouseRegion.

These widgets are smart enough to delegate whether they detect a hit (and therefore whether they can detect a gesture) to the child - although HitTestBehavior.deferToChild may be required for some widgets to enable this functionality.

This means the layer can report whether it had any form of hit, and the handler widget can detect whether the gesture performed on it actually triggered a hit on the layer below.

// Inside the map build...
MouseRegion(
  hitTestBehavior: HitTestBehavior.deferToChild,
  cursor: SystemMouseCursors.click, // Use a special cursor to indicate interactivity
  child: GestureDetector(
    onTap: () {
      // Handle the hit, which in this case is a tap
      // For example, see the example in Hit Handling (below)
    },
    // And/or any other gesture callback
    child: PolylineLayer(
      hitNotifier: hitNotifier,
      // ...
    ),
  ),
),

4. Hit Handling

Once a LayerHitResult object is obtained, through the hit notifier, you can retrieve:

• hitValues: the hitValues of all elements that were hit, ordered by their corresponding element, first-to-last, visually top-to-bottom

• coordinate: the geographic coordinate of the hit location (which may not lie on any element)

• point: the screen point of the hit location

Because the HitNotifier is a special type of ValueNotifier, it can be both listened to (like a Stream), and its value instantly retrieved (like a normal variable). Therefore, there are two ways to retrieve a LayerHitResult (or null) from the notifier:

• Using .value to instantly retrieve the value This is usually done within a gesture handler, such as GestureDetector.onTap, as demonstrated below.

• Adding a listener (.addListener) to retrieve all hit results This is useful where you want to apply some custom/advanced filtering to the values, and is not a typical usecase.

// Inside a gesture detector/handler

final LayerHitResult? hitResult = hitNotifier.value;
if (hitResult == null) return;

// If running frequently (such as on a hover handler), and heavy work or state changes are performed here, store each result so it can be compared to the newest result, then avoid work if they are equal 

for (final hitValue in hitResult.hitValues) {}

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

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

Interactivity

PolygonLayers and Polygonss support hit detection and interactivity.

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.

Inverted Filling

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.

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

Overview

Here's some highlights:

We've also made other changes to improve the experience for your users. Checkout the CHANGELOG for the curated changes, and the full commit listing for all the small details.

Migration

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

MarkerLayer(
  markers: [
    Marker(
      point: LatLng(30, 40),
      width: 80,
      height: 80,
      child: FlutterLogo(),
    ),
  ],
),

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.

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

PolylineLayer(
  polylines: [
    Polyline(
      points: [LatLng(30, 40), LatLng(20, 50), LatLng(25, 45)],
      color: Colors.blue,
    ),
  ],
),

Pattern

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.

dotted and dashed patterns should 'fit' the Polyline they are applied to, otherwise the final point in that line may not be visually clear. The fit can be adjusted when defining the pattern through the PatternFit enum.

Interactivity

PolylineLayers and Polylines support hit detection and interactivity.

Performance Optimizations

Culling

To improve performance, line segments that are entirely offscreen are effectively removed - they are not processed or painted/rendered. This is enabled by default and disabling it is not recommended.

Simplification

To improve performance, polylines are 'simplified' before being culled and painted/rendered. The well-known Ramer–Douglas–Peucker algorithm is used to perform this, and is enabled by default.

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

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

To adjust the quality and performance of the simplification, the maximum distance between removable points can be adjusted through the simplificationTolerance parameter. Increasing this value (from its default of 0.4) results in a more jagged, less accurate (lower quality) simplification, with improved performance; and vice versa. Many applications use a value in the range 0 - 1.

To disable simplification, set simplificationTolerance to 0.

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 OSRM (which includes a public demo server) and Valhalla. 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 'google_polyline_algorithm', together with a custom method. You can use the code snippet below, which can just be pasted into a file and imported whenever needed:

import 'package:latlong2/latlong.dart';
export 'package:google_polyline_algorithm/google_polyline_algorithm.dart'
    show decodePolyline;

extension PolylineExt on List<List<num>> {
  List<LatLng> unpackPolyline() =>
      map((p) => LatLng(p[0].toDouble(), p[1].toDouble())).toList();
}

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

import 'unpack_polyline.dart';

decodePolyline('<encoded-polyline>').unpackPolyline(); // Returns `List<LatLng>` for a map polyline

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.

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

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 behviour, 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 MapOptions.

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.

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.

When the state of a MapCamera changes, because of an update to its position or zoom, for example, a MapEvent, which can be handled by you.

Catching All Events

• 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

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:

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.

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

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

Vector Usage

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.

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

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

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

Bulk Downloading

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

Bundled Map Tiles

If you have a set of custom raster tiles that you need to provide to all your users, you may want to consider bundling them together, to make a them easier to deploy to your users. Bundles can be provided in two formats.

Contained

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

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

Uncontained

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

AssetTileProvider

You can ship an entire tile tree as part of your application bundle, and register it as assets in your app's pubspec.yaml.

This means that they will be downloaded together with your application, keeping setup simple, but at the expense of a larger application bundle size.

FileTileProvider

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

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

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.

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.

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.

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.

Other configurations

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

Adding Attribution

Prebuilt Styles

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

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!

2. Create an account

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

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.

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

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

Contributing

Apply To Be A Maintainer

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:

Tile Container Parsers/Providers

Better Markers

Marker Clustering

Better Polylines & Polygons

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

Most plugins create either new Tile Providers, or new Layers. 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 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

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

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

Support Us

Please consider donating to keep this project going! We're extremely grateful all donations of any size. 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).

(Donation links appear below)

• Donate with GBP (Bacs Direct Debit, + standard options)

• Donate with EUR (iDEAL, SEPA Direct Debit, + standard options)

• Donate with USD (ACH/Bank Transfer, + standard options)

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

• V3ntus

• OCELL

• ishcherbina

• ... and everyone else who donated anonymously

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.

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.

(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