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

Flags

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

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

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

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

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

Cursor/Keyboard Rotation

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

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

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

"Win" Gestures

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.

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

Live Web Demo

Prebuilt Artifacts

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

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

The Web artifact requires unzipping and serving, as it contains more than one unbundled file. You may be able to use 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.

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.

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.

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

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!

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

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!

Get Help

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

• Check the below, and double check the documentation

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

• Then, for support & everything else: ask in or

FAQs

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

We think flutter_map hits the spot for many Flutter apps. Find out why!

Feature Highlights

Independent Works

Project Showcase

Non-OSS Sponsors

OSS and/or Non-Profit Projects

Install

From

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

From

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

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

Additional Setup

Web

Wasm/Renderer

CORS

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

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

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:

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

• 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

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

Custom CRS

FM does have some support for using alternative CRSs.

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 the interactable 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

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

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.

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:

This will attach the widget to the state of the map, causing it to rebuild whenever the depended-on aspects change. See for more information.

Accessing Aspects Elsewhere

MapCamera

To access the MapCamera outside of a FlutterMap descendant, first .

Then use the camera getter on the MapController instance.

MapController

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

MapOptions

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.

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 (___) with your API key

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:

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

Keep Alive

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

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

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

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:

You can create and register your custom projection in multiple ways, but the recommended is to use a Proj4 definition string from epsg.io. 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:

For more possible ways to register proj4.Projection see .

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

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:

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.

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

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)

• All the previous maintainers:

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

  • @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:

Contributing

Apply To Be A Maintainer

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:

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.

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

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

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

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.

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)

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.

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

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

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

• Specifying a callback method in MapOptions.onMapEvent

Catching Specific Events

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

• onTap

• onLongPress

• onPositionChanged

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

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:

1. (lightweight and MIT licensed)

2. (also includes , but GPL licensed)

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

Bulk Downloading

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:

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:

• : (when using vector tiles)

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

Uncontained

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

AssetTileProvider

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

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

FileTileProvider

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

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

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

Alignment

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

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

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

Rotation

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

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

Handling Gestures

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

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:

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

Pattern

Polyline

The tileProvider parameter in TileLayer takes a TileProvider object specifying a 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:

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.

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:

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.

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

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

Interactivity

PolygonLayer

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