As briefly described in #map-widget, the children property takes a list of Widgets, which will be stacked on top of each other (last on top). These can be any Widget, such as a FutureBuilder or StreamBuilder, but are usually Layers which are provided by this library or plugins.

There is also the nonRotatedChildren property, which work similarly as their 'rotatable' counterpart, but - as the name suggests - do not get rotated as the map gets rotated. For example, the AttributionWidget should be used inside nonRotatedChildren instead of children, as it needs to remain vertical and therefore readable.

As a minimum, all maps should have a Tile Layer, as this is what actually displays any map. Other layers are available, such as markers/waypoints and lines.

You can add polygons to maps to display shapes made out of points to users using PolygonLayer().

FlutterMap(
    options: MapOptions(),
    children: [
        PolygonLayer(
            polygonCulling: false,
            polygons: [
                Polygon(
                  points: [LatLng(30, 40), LatLng(20, 50), LatLng(25, 45),],
                  color: Colors.blue,
                ),
            ],
        ),
    ],
),

Polygons (polygons)

As you can see PolygonLayerOptions() accepts list of Polygons. Each determines the shape of a polygon by defining the LatLng of each corner. 'flutter_map' will then draw a line between each coordinate, and fill it.

More Polygon Operations

'flutter_map' doesn't provide any public methods to manipulate polygons, as these would be deemed out of scope.

However, some useful methods can be found in libraries such as 'latlong2' and 'poly_bool_dart'. These can be applied to the input of Polygon's points argument, and the map will do it's best to try to render them. However, more complex polygons - such as those with holes - may be painted inaccurately, and may therefore require manual adjustment (of holePointsList, for example).

You can add markers to maps to display specific points to users using MarkerLayer().

Markers (markers)

As you can see MarkerLayerOptions() accepts list of Markers which determines render widget, position and transformation details like size and rotation.

A tile layer displays raster map tiles in a grid pattern, from a tile source such as a remote server or file system. This might look something like this:

Subdomains (subdomains)

Takes a list of strings specifying the available subdomains. For example:

One will be chosen differently every request by the tile provider to replace the '{s}' part of the urlTemplate.

If you are not sure of the correct values for your server, don't specify anything. For example, the urlTemplate used in the example above will work without the '{s}' part and any subdomains specified.

Tile Bounds (tileBounds)

Takes a LatLngBounds to restrict the layer to only loading tiles within that area. For example:

will restrict the tiles to only loading Egypt (a square-ish country). Note that the map can still be moved freely outside of this range.

An example use-case might therefore be loading a specialised map for a region and just a basic map style elsewhere (different urlTemplates). In this case, the bounded layer should go beneath the unbounded layer. Setting backgroundColor: Colors.transparent is also necessary on the bounded layer to ensure the other layer is visible elsewhere.

Error/Fallback Tile (errorImage)

will use a sea tile on every tile that cannot be fetched.

This is an optional parameter that has no default. If this is not specified, and tiles are unable to be fetched, then the background color.

Tile Size (tileSize)

Takes a double number specifying the width and height (in pixels) of each tile. As tiles are always square, only one number is needed.

This defaults to 256, as most tile servers serve 256x256px tiles.

Custom Tile Builder (tileBuilder)

Takes a callback function, in the format Widget Function(BuildContext context, Widget tileWidget, Tile tile). For example:

will show the tile's coordinate on the tile.

There is also tilesContainerBuilder available, which works slightly differently, but is recommended when the same builder can be used on every tile, for performance reasons.

There are predefined tile builders available, such as a dark mode emulator and a loading time debugger.

Reset Stream (reset)

Takes a Stream<void>?, that causes the layer to 'reset' when an event is received. This might be necessary after updating the templateUrl. For example:

URL Template (urlTemplate)

This parameter is not strictly required, but the map is essentially useless without it specified with a valid URL.

Takes a string that is a valid URL, which is the template to use when the tile provider constructs the URL to request a tile from a tile server. For example:

will use the OpenStreetMap Tile Server.

The '{s}', '{z}', '{x}' & '{y}' parts indicate where to place the subdomain, zoom level, x coordinate, and y coordinate respectively. Not providing at least the latter 3 parts won't necessarily throw an error, but the map won't show anything.

Package Name (userAgentPackageName)

Takes a String, which should be the unique package name (eg. com.example.app). For example:

This string is used to construct a 'User-Agent' header, sent with all tile requests (on platforms other than the web, due to Dart limitations), necessary to prevent blocking by tile servers.

Constructed agents are in the format: 'flutter_map (packageName)'. If the package name is not specified, 'unknown' is used in place.

Tile Provider (tileProvider)

For more information, see:

Retina Mode (retinaMode)

If true, the providers should request four tiles of half the specified size and a bigger zoom level in place of one to utilize the high resolution. In this case, you should set MapOptions's maxZoom should be maxZoom - 1 instead.

For example, this is the recommended setup:

You can add lines to maps to display paths/ways made out of points to users using PolylineLayer().

Polylines (polylines)

As you can see PolylineLayerOptions() accepts list of Polylines. Each determines the shape of a polyline by defining the LatLng of each point. 'flutter_map' will then draw a line between each coordinate.

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.

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

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.

Network Tile Providers

Network tile providers can take a Map<String, String> of custom headers. Note that the that is automatically generated will not override any 'User-Agent' header if specified here. On the web, the 'User-Agent' header is not sent, as the browser controls the user agent.

Whilst not on the web, network tile providers can take a custom HttpClient/RetryClient, if you need to use it for whatever reason.

NetworkNoRetryTileProvider()

This is the default tile provider.

This tile provider uses the templateUrl to get the appropriate tile from the Internet, and it won't retry the request if it fails.

There is no guarantee about the default caching behaviour, but tiles should be cached until an application restart.

NetworkTileProvider()

This tile provider uses the templateUrl to get the appropriate tile from the Internet, but it will retry the request as specified in the RetryClient (which can be customised as needed when not on the web).

There is no guarantee about the default caching behaviour, but tiles should be cached until an application restart.

Local Tile Providers

These tile providers use the templateUrl 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

Bundled Map Tiles

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.

Caching & Bulk Downloading

To help choose whether FMTC or DIY is more appropriate for your usecase, please see:

You can add circle polygons to maps to users using CircleLayer().

Before publishing your app to users, you should credit the tile server you use, this library, and potentially and plugins you use.

FlutterMap(
    options: MapOptions(),
    nonRotatedChildren: [
      AttributionWidget.defaultWidget(
        source: '© OpenStreetMap contributors',
        onSourceTapped: () {},
      ),
    ],
),

Default Builder

The default builder, as shown above, can be used to get a classic attribution box appearance quickly without much setup. Just add a source and a function (if you want a clickable link to appear), and 'flutter_map' automatically gets credited.

Custom Builder

Alternatively, create your own box from scratch by omitting the defaultWidget constructor from the widget. Then you can build a custom widget as you would normally.