1 of 37

v4

flutter_map

Mapping package for Flutter, based off of 'leaflet.js'. Simple and easy to learn, yet completely customizable and configurable, it's the best choice for mapping in your Flutter app.

Setting up an interactive and compliant map is simpler than making your lunch-time coffee! It can be accomplished in just over 20 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!

How Does It Work?

If you don't know about standard map things, such as the latitude/longitude system and projections, you should probably read about these first!

If you want a truly British insight into this, look no further than: & . Otherwise I'd recommend something else.

This library is similar to most other mapping libraries in other languages, so this applies to most other mapping libraries as well.

A mapping library is usually just a wrapper for a particular language that handles requests to servers called 'tile servers', and displays it in an interactive view for the user.

What is a Tile Server?

A tile server is a server accessible on the Internet by everyone, or by only people holding the correct API key.

There are four main types of server configuration, two of which are used together by any server: WMS or WMTS (aka. CARTO) & vector or raster. This wiki will focus on WMTS raster servers, such as the main OpenStreetMaps server, as it is the most commonly used option and is easier to setup and explain for beginners, but you can read about the options for WMS later on in this wiki. At the moment, support of vector tiles is limited, but experimental functionality can be added through an existing community maintained plugin.

Simplified, the server holds multiple images in a directory structure that makes it easy to find tiles without searching for references in a database beforehand (see below). These images put together make up the whole world, or area that that tile server supports. One tile is usually really small when rendered, under 20KB for most tiles. However, the entire planet data consumes 1.5TB when un-rendered and uncompressed from the 110GB download archive. When all tiles are rendered, they add up to over 54TB! Most servers render tiles on-the-fly to get around this.

The main tile server that's free to use and open-source is the Open Street Maps tile server, as mentioned above, a server which provides access to millions of tiles covering the whole Earth. that get updated and maintained by the general public. You can .

The , but this page provides some basics, roughly copied from that page.

The standard Slippy Map path looks like this: '/zoom/x/y.png' or '/x/y/zoom.png'. To note, the image format does not have to be '.png', tile servers also commonly serve as '.jpg' images.

You may also see '/?x={x}&y={y}&zoom={z}', which isn't quite the same as the Slippy Map convention, but it works in essentially the same way, so the below text still applies.

Zoom refers to the zoom level. 1 is the lowest zoom level and contains the whole world in one tile. The higher the number, the more the zoom, and the more the detail, and therefore the less space covered. You can read more about this at . Most servers go up to 18, some up to 19, but no servers (as of writing) have a maximum limit above 22.

X and Y are values corresponding to the longitude and latitude of a location, however they are not actual longitude and latitude. See .

These images show the mathematics required to convert between Latitude and Longitude & the x/y/z format and vice-versa respectively. All credit for the above images goes to the Open Street Maps foundation.

In this 'flutter_map' package, the classes that conduct this maths to get these tiles are called 'tile providers'.

However, these do a lot more than just the maths. They do the maths, format the appropriate URL, potentially stagger the URL (not to get rate limited by the browser or engine), make the request, get the image, process (and potentially store) the image and finally give it back to the main process to paint onto the map for the user to see.

Unless you choose to implement your own custom tile provider, you should never need to handle this yourself.

For more information about setting up a tile provider within the API, see .

Once the tile provider has dealt with the tile, it sends it to a map layer to get painted onto the map. This can be done using canvases (such as in HTML5 for the web), or, in the case of 'flutter_map', Flutter widgets.

The map layers also handle user interaction, such as panning, zooming, rotating and tapping.

Raster vs Vector Tiles

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

Getting Started

Installation

All users should also to work with coordinates in 'flutter_map'.

In the event that the LatLng object provided by that library conflicts with another, for example the one provided by Google Maps, you may need to .

From

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

flutter pub add flutter_map
flutter pub add latlong2

From

Commits available from Git (GitHub) may not be stable. Only use this method if you have no other choice.

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:

pubspec.yaml

dependency_overrides:
    flutter_map:
        git:
            url: https://github.com/fleaflet/flutter_map.git
            # ref: main

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';
import 'package:flutter_map/plugin_api.dart'; // Only import if required functionality is not exposed by default

Before continuing with usage, make sure you comply with the appropriate rules and ToS for your server. Some have stricter rules than others. This package or the creator(s) are not responsible for any violations you make using this package.

Additional Setup

Web

Always compile to web using the CanvasKit renderer instead of the HTML renderer, even on mobile devices.

Failure to do so leads to severely impacted performance. Additionally, some features may be broken - for example, tile fading doesn't work when rendering in HTML.

For more information about web renderers, see .

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.

AndroidManifest.xml

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

Examples

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!

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 for this purpose.

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

Migrating To v4

This update brings major breaking changes for all users.

Please refer to the sections below for information on how to migrate your project. This will contain the changes that most users may need to make, but not all changes.

For a full list of changes, please see the full , and make use of the old and new API reference.

One of the major cores of flutter_map has been upgraded to the 21st century by a generous contributor (@rorystephenson). This increases the simplicity of the layer, and its performance!

Grey boxes get a little boring, don't you think? We think so as well, so we've developed a new interactive animated attribution layer that should cover all your needs.

Usage

Base Widget

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

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.

Options

To dictate what the map can/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

Layers

To display anything on the map, you'll need to include at least one "layer"!

Multiple layers can be used - similar to a Stack - each one showing different data in different ways, from actual map tiles () to shapes on top of them (), and even just your own custom layers ().

Each layer has its own configuration and handling, but can also access the map's state/configuration, as well as be controlled by it.

Layers are usually defined in the children property of the FlutterMap - as is with the

Controller

To programatically interact with the map (such as panning, zooming and rotating) and receive it's events, you'll need a MapController.

If building a custom layer (), consider using FlutterMapState directly instead.

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.

final mapController = MapController();

@override
Widget build(BuildContext context) =>
    FlutterMap(
        mapController: mapController,
        ...
    );

Avoid disconnecting the map from the controller, as it can cause problems. If you need to change the map's contents:

Change its children (layers) individually

Usage In `initState()`

It is a fairly common requirement to need to use the MapController in initState(), before the map has been built. Unfortunately, this is not possible, as the map must be built for the controller to be attached.

This isn't a problem however! The MapOptions contains an onMapReady callback (see ) is called once when the map is initialised, and the initialised map controller can be used freely within it.

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.

Layers

Tile Layer

CARTO/XYZ/Slippy Map Only

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 the CARTO/XYZ/Slippy Map standard, where the mapping library (flutter_map) fills in XYZ placeholders in a URL.

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

You must comply to your tile server's ToS. Failure to do so may result in you being banned from their services.

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

This package is not responsible for your misuse of any tile server.

It is possible to use more than one tile layer, and can be used with transparency/opacity.

The children list works like the children of a Stack: last is on top.

Tile Providers

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

This has a default of NetworkNoRetryTileProvider, which is recommended for most setups for better performance, unless your tile server is especially unreliable, or you need a local tile provider.

Custom TileProviders can be implemented by your application or other libraries. These may not conform to the usual rules above, and may additionally have their own parameters.

Marker Layer

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

Marker rotation support isn't built in (other than counter rotating to the map, to ensure the marker is always displayed right side up), but can easily be implemented through a rotation widget, such as Transform.rotate.

Polygon Layer

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

'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

Polyline Layer

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

Due to the nature of the Earth being a sphere, drawing lines perfectly requires large amounts of difficult maths that may not behave correctly when given certain edge-cases.

Avoid creating large polylines, or polylines that cross the edges of the map, as this may create undesired results.

Excessive use of polylines may create performance issues.

Consider using one of the methods below if you encounter jank:

Keep saveLayers

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!

A good open source option is OSRM, but if you want higher reliability and more functionality such as real-time based routing, you may want to try a commercial solution such as Mapbox or Google Maps.

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:

Circle Layer

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

Overlay Image Layer

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

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

Attribution Layer

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. All of these should be inserted into the map's nonRotatedChildren.

You must comply to your tile server's ToS. Failure to do so may result in you being banned from their services.

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

This package is not responsible for your misuse of another tile server.

Please consider crediting flutter_map. It helps us to gain more awareness, which helps make this project better for everyone!

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

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.

WMS Usage

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.

Plugins

Making A Plugin

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.

Unfortunately, you may need more niche functionality that hasn't been provided by an existing plugin or by 'flutter_map' itself. Alternatively, you may have found a gap in functionality that not everyone will need, but some people will: in this case, it's likely the maintainers will ask you to submit a plugin instead of a pull request.

Plugins can add/change a wide variety of functionality, so this guide is not exhaustive. However, it will help with the most common requirements. Each subpage covers a specific part of the plugin API, and the section below sets out requirements for plugins to be accepted into the list.

If you've made your own plugin that you're willing to share, you can add it to this list by creating a pull request in GitHub. We're always looking forward to see what you've made!

When submitting a plugin & PR, please ensure the plugin:

Creating New Tile Providers

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.

Some useful steps are below, but there are more properties of a TileProvider that can be overridden.

To create your own usable TileProvider, the first step is making a class that extends the abstract class. It is not recommended to implement the base, as this will require overriding methods unnecessarily for most custom providers.

Creating New Layers

Creating a new map layer is just as easy as it is to create a normal StatelessWidget or StatefulWidget.

Only one method call is needed to 'connect' the widget to the map state: FlutterMapState.maybeOf(). This call does two important things:

Cause the widget/layer to rebuild automatically when required (if in the build method)
Expose the map's internal state, meaning that it's information (such as zoom) can be accessed

You can see an example of how this is done below:

Tile Servers

Using Mapbox

To integrate with 3rd party mapping libraries, Mapbox provides an alternative to the normal 'Style URL' for each map style (and any custom map styles).

The 'CARTO' 'Integration URL' contains all the information and placeholders that flutter_map requires to display a map. Tiles requested through this endpoint consume the 'Static Tiles API' quota.

Once you have the appropriate URL for your desired map style (see ), use it in a TileLayer's urlTemplate as normal.

Retina tiles (high-DPI) tiles are used by default ('@2x'). The maximum zoom level that Mapbox supports is 22, so it is recommended to set maxNativeZoom or maxZoom

Using Thunderforest

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.

Using Stadia Maps

'flutter_map' is in no way associated or related with Stadia Maps.

Stadia Maps' home page: Stadia Maps' pricing page: Stadia Maps' documentation page:

To integrate with 3rd party mapping libraries, Stadia Maps provides an alternative to the normal 'Static Maps Base URL' for each map style.

The 'Raster XYZ PNGs' URL contains all the information and placeholders that flutter_map requires to display a map. Tiles requested through this endpoint consume the 'Styled Raster Map Tiles' credits.

Once you have the appropriate URL for your desired map style (see Styles), use it in a TileLayer's urlTemplate as normal.

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.

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

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

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.

Offline Mapping

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
Bulk downloading 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

The aims to solve the first two points. FMTC is designed to be easy to implement, but also sufficiently advanced to cover most (if not all) use cases.

However, using simpler packages in a DIY solution can be a better option in some cases. You'll need to implement a custom TileProvider backed by an alternative image provider or cache lookup system: see .

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.

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.

Other Options

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

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

Google Maps does not document a static raster tile server. Therefore, flutter_map is unable to show Google Maps.

There is an undocumented endpoint available, however it violates the Google Maps Platform ToS.

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.

Frequently Asked Questions

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

Contributing

'flutter_map' is only as big and useful as it is because of contributors. You can see a , and there are currently , each potentially from a new contributor.

Therefore, your contribution would be greatly appreciated, so we've written a guide to help you contribute successfully.

Do you think your contribution is essential to 'flutter_map'/useful to all users?

If not, then creating a plugin might be a good idea. To do this, see the Plugins section in these docs: there is advice, starting templates and a few rules to bear in mind. Plugins are preferred when possible as they keep the base library lightweight and easy to understand.

If you think it might be, continue onwards.

Is the contribution to fix a bug? Do you feel comfortable coding it yourself?

Credits

Thanks to everyone who has contributed to flutter_map in anyway, you've helped make it the most popular non-commercially owned mapping solution for Flutter. As well as those that have contributed directly to the code, this includes everyone on the Discord server, everyone who's following the progress, and everyone that's participating in discussions and issues.

If you want to contribute to the codebase, please visit the instructions. We'd love to have your input!

In particular, thanks go to:

John P Ryan - the founder of this project

v4

flutter_map

How Does It Work?

What is a Tile Server?

Raster vs Vector Tiles

Getting Started

Installation

From

From

Import

Additional Setup

Web

Android

Examples

Migrating To v4

Usage

Base Widget

Placement Recommendations

Options

Layers

Controller

Initialisation

Usage In initState()

Layers

Tile Layer

Tile Providers

Marker Layer

Polygon Layer

Polyline Layer

Routing/Navigation

Converting Formats

Circle Layer

Overlay Image Layer

Attribution Layer

RichAttributionWidget

WMS Usage

Plugins

Making A Plugin

Creating New Tile Providers

Creating New Layers

Tile Servers

Using Mapbox

Using Thunderforest

Using Stadia Maps

Offline Mapping

Other Options

Other servers

Serving your own tiles

Frequently Asked Questions

Contributing

Credits

How Does It Work?

What is a Tile Server?

Additional Setup

Web

Android

Tile Providers

Layers

Raster vs Vector Tiles

Examples

Circle Layer

WMS Usage

Using Thunderforest

Raster Tiles

Vector Tiles

Using Vector Tiles

Network Tile Providers

NetworkNoRetryTileProvider()

NetworkTileProvider()

Local Tile Providers

AssetTileProvider()

FileTileProvider()

Offline Mapping

'Slippy Map' Convention

Zoom

X & Y

Tile Providers

Map Layers

Live Web Demo

Prebuilt Artifacts

Usage In `initState()`

`RichAttributionWidget`

`NetworkNoRetryTileProvider()`

`NetworkTileProvider()`

`AssetTileProvider()`

`FileTileProvider()`

Extending The Base `TileProvider`

Overriding `getImage`

Overriding `getTileUrl`

`onTap` Support

Usage In `initState()`

`RichAttributionWidget`

`SimpleAttributionWidget`

Through `MapController`

Through `MapOptions`

`TileLayer` Changes

Better `Marker`s

Better `Polyline`s & `Polygon`s