Why choose flutter_map?

Code Demo

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

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

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: Why choose flutter_map?. But don't just take it from us - check out who else is using flutter_map, and what they think of it!

Community Studies

Project Showcase

These great projects all make use of flutter_map!

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

Non-OSS Sponsors

OSS and/or Non-Profit Projects

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.

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

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

Keep Alive

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

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

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 .

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

Raster Tiles

Raster tiles are the 'older' type of tile, and are raster images (usually .png or .jpg). These tiles are good because they can render quickly and easily, can be viewed without special software, and are readily available from most mapping services. As such, this makes them the popular choice for beginners.

However, raster tiles cannot be easily themed: a theme needs a whole new set of map tiles. This makes apps using light and dark themes have mismatching maps. As well as this, raster tiles usually have larger file sizes meaning slower download times, and they can become blurred/pixelated when viewed at a larger scale: a problem for users when zooming between zoom levels. Another issue is that shapes/text inside tiles cannot be rotated, hence the name 'static tiles': therefore, rotating the map will not rotate the name of a road, for example.

Vector Tiles

Vector tiles can be considered the 'newer' standard. These images might contain a specialised format (such as .pbf) dictating the mathematics and coordinates used to draw lines and shapes. Because these tiles are drawn at render time instead of at request/server time, theming can be used to make the map fit in better with an app's theme. The math-based image means that the images/tiles can be scaled without any loss of clarity.

However it does add complexity to the rendering process as each element needs to be parsed and painted individually, meaning an impact to performance. Text elements and certain shapes can also be rotated (unlike raster tiles) to match the user's orientation, not the orientation of the map; but calculating this rotation needs to be done every frame, meaning an even larger impact on performance.

Using Vector Tiles

Due to the complications mentioned above, 'flutter_map' does not natively support vector tiles. However, vector tiles can be used with a to do this.

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

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!

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.

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 ), such as applying GestureDetectors around Marker.children

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

We'll donate 15% of what we receive to the OpenStreetMap Foundation, as a thanks for their excellent work. The remainder goes directly to improving flutter_map, whether that's through supporting external contributors through bounties, covering any unforeseen and future costs, or supporting the maintainers.

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

Past Supporters

is extensible.

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

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

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

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:

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

Enabling/disabling unbounded horizontal scrolling

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

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

Constraining the camera vertically/latitudinally

It's now possible to remove the grey edges that appear at the top and bottom of the map when zoomed far out.

To do this, set the MapOptions.cameraConstraint parameter:

Feature layers & multi-worlds

Each square of map that is repeated longitudinally is referred to as a "world". By default, the feature layers (for example, PolygonLayer, PolylineLayer, CircleLayer, and MarkerLayer) will repeat their features across the layers, so that each world looks identical.

In the PolylineLayer & PolygonLayer, this can be disabled by setting the drawInSingleWorld property.

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.

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.

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

Web Demo

Prebuilt Artifacts

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

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

The Web artifact requires unzipping and serving, as it contains more than one unbundled file. You may be able to use for this purpose.

Build From Source

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

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

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

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

Mobile vs Static Layers

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

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

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

Layers With Elements: "Feature Layers"

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:

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

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

Submitting A New Plugin

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

When submitting a plugin, please ensure the plugin:

• preferably includes flutter_map_ in the name, by convention

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

• is available via a standard pub.dev package installation

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

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

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

NetworkTileProvider

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

For more information, check the API documentation.

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 single point features - including arbitrary widgets - 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.

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

1. Creating A Layer Widget

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

2. Hooking Into Inherited State

Then, there are three possible methods that could be used to retrieve separate 'aspects' of the state of the map.

Calling these inside a build method will also cause the layer to rebuild automatically when the depended-on aspects change.

Depend On It

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

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.

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:

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

  • camera center inside bounds:

Custom CRS

FM does have some support for using alternative CRSs.

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:

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.

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.

Tile providers can support the MapCachingProvider contract/interface to support built-in caching. See .

(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

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

Configuring

The URL includes an '@2x' string, which forces usage of high-definition tiles on all displays, without extra setup.

Should you need to let flutter_map interfere, and only use retina tiles on retina/high-density displays, replace it with the '{r}' placeholder, then see for more information.

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

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

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

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

Flags

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

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

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

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

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

For example, to disable flinging:

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

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

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

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

Overview

Here's some highlights since v8.0:

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

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

Migration

To v8.2

To v8.0

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

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.

Multi-Worlds

The PolylineLayer paints its Polylines across all visible worlds by default. This can be changed.

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 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 (which includes a public demo server) and . You can also use a commercial solution such as Mapbox or Google Maps - these can often give more accurate/preferable results because they can use their traffic data when routing.

Converting Formats

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

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

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

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

Caching aims to:

• Improve developer experience by:

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

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

It does, however, come at the expense of usage of on-device storage capacity.

Offline mapping and caching can also be implemented in other ways. See for more information.

Configuring the built-in provider

To configure the default provider, provide arguments to the getOrCreateInstance factory constructor. Usually this is done when constructing the TileLayer/TileProvider:

By default, caching occurs in a platform provided cache directory. The operating system may clear this at any time.

By default, a 1 GB (soft) limit is applied to the built-in caching. This limit is only applied when the cache provider is initialised (usually when the first tiles are loaded on each app session).

HTTP headers are used to determine how long a tile is considered 'fresh' - this fulfills the requirements of many tile servers. However, setting overrideFreshAge allows the HTTP headers to be overridden, and the tile to be stored and used for a set duration.

The tileKeyGenerator can be customized. The callback accepts the tile's URL, and converts it to a key used to uniquely identify the tile. By default, it generates a UUID from the entire URL string. However, in some cases, the default behaviour should be changed:

Deleting the cache

With the default BuiltInMapCachingProvider, it is possible to delete the cache contents in two ways:

• When the app is running, destroy the current instance and set the deleteCache argument to true (then optionally create a new instance if required, which happens automatically on the next tile load by default)

• When the app is not running, users may delete the storage directory

Using other providers

You can also use any other MapCachingProvider implementation, such as provided by plugins, or ! They may support the web platform, unlike the built-in cache.

You should check that plugin's documentation for information about initialisation & configuration. You will always need to pass it to the cachingProvider argument of a compatible TileProvider.

Disabling built-in caching

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

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.

The following layers support 'interactivity':

• Polyline Layer

• These layers don't provide their own 'gesture' callbacks, such as onTap

• These layers automatically perform hit testing with Flutter APIs

Detecting hits & gestures

You may be used to using widgets such as GestureDetector or MouseRegion to detect gestures on other normal widgets. These widgets ask the child to decide whether they were hit, before doing their own logic - e.g. converting the hit to the appropriate callback depending on the gesture.

Because flutter_map's layers are just widgets, they can also be wrapped with other widgets and inserted into the map's children.

This means you can simply wrap layers with GestureDetectors (for example) which will execute callbacks when the layer is hit. Layers tell Flutter they were hit only if at least one of their elements (such as a Polygon) were hit.

Here's an example of how you would detect taps/clicks on polygons, and convert a cursor to a click indicator when hovering over a polygon:

Identifying hit elements

To identify which elements (such as Polygons) were hit, flutter_map APIs are required:

• A LayerHitNotifier exposes results of hit tests

• Elements may have metadata known as hitValues attached, which identify that specific element - these are then exposed by the hit notifier's events/values.

• The entire system may be strongly typed through type parameters on various parts, if all the hitValue

Example

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

Interactivity

PolygonLayers and Polygonss support hit detection and interactivity.

Multi-Worlds

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

Performance Optimizations

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

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

Painter Fill Method

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

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

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

Inverted Filling

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 . These can be applied to the input of Polygon's points argument, and the map will do it's best to try to render them. However, more complex polygons - such as those with holes - may be painted inaccurately, and may therefore require manual adjustment (of holePointsList, for example).

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

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

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