flutter_map_maplibre

This package offers performant Mapbox Vector Tiles (MVT) support for flutter_map powered by maplibre, which renders maps with the native MapLibre SDKs.

  • MapLibreLayer: use a MapLibreMap as a layer inside of FlutterMap.
  • FlutterMapAdapter: use flutter_map layers (markers, polylines, ...) inside of MapLibreMap.

Pub Version likes Pub Points Pub Downloads

GitHub last commit stars GitHub issues codecov

Showcase

Getting started

  1. Add the dependencies to your pubspec.yaml file.
dependencies:
  flutter_map: ^8.0.0
  flutter_map_maplibre: ^0.1.0-pre.2
  maplibre: ^0.4.0-pre.2
  1. Follow the platform specific setup steps for the maplibre package:
  1. Import the packages:
import 'package:flutter_map/flutter_map.dart';
import 'package:flutter_map_maplibre/flutter_map_maplibre.dart';
import 'package:latlong2/latlong.dart';
// Use a prefix for maplibre to avoid name clashes with flutter_map.
import 'package:maplibre/maplibre.dart' as ml;

Usage

There are two ways to bridge the gap between flutter_map and maplibre:

MapLibreLayer FlutterMapAdapter
Root widget FlutterMap MapLibreMap
Gestures handled by flutter_map handled by maplibre
Camera control flutter_map MapController maplibre MapController
Use it to add a vector map to an existing FlutterMap use flutter_map layers in a MapLibre map

Each solution has its pros and cons. You can check out both implementations in the hosted example app.

Use MapLibre as a vector layer in FlutterMap

Add a MapLibreLayer to the children of FlutterMap. flutter_map handles all gesture inputs and the MapLibreLayer follows its camera.

@override
Widget build(BuildContext context) {
  return FlutterMap(
    mapController: _mapController,
    options: MapOptions(
      initialZoom: 4,
      initialCenter: const LatLng(0, 0),
      maxZoom: 20,
      // maplibre does not support an unbound latitude
      cameraConstraint: CameraConstraint.contain(
        bounds: LatLngBounds(
          const LatLng(-90, -180),
          const LatLng(90, 180),
        ),
      ),
    ),
    children: [
      // uses the OpenFreeMap liberty style by default
      const MapLibreLayer(),
      // add other flutter_map layers here
    ],
  );
}

Use another style with the style parameter:

MapLibreLayer(
  style: ml.MapStyle.url('https://tiles.openfreemap.org/styles/liberty'),
)

MapLibreLayer parameters

Parameter Description
style The map style (MapStyle.url, .json, .asset, .file). Defaults to OpenFreeMap liberty.
minZoom Minimum zoom level of the MapLibre map.
maxZoom Maximum zoom level of the MapLibre map.
maxBounds Restricts the camera of the MapLibre map to a GeoBox.
layers MapLibre layers that are rendered on top of the style (MapLibreMap.layers).
children Widgets that are placed on top of the MapLibre map (MapLibreMap.children).
paused Pauses the rendering of the map.
onMapCreated Called with the maplibre MapController when the map got created.
onStyleLoaded Called with the StyleController when the style has been loaded.
Event callbacks Individually typed callbacks matching MapLibreMap, including clicks, drags, camera changes, and rendering events.

MapLibreLayer exposes each MapLibre event callback as an individual typed parameter, with the same names as MapLibreMap: onClick, onDoubleClick, onSecondaryClick, onLongClick, onDragStart, onDrag, onDragEnd, onPointerMove, onPointerLeave, onCameraMoveStart, onCameraMove, onCameraMoveEnd, onIdle, onError, onStyleImageMissing, onLoadingStarted, onLoadingFinished, onSourceChanged, onTile, onRenderFrame, onRenderMap, onGlyphs, onSprite, onRenderingChanged, onResize, onContextLost, onContextRestored, and onProjectionChanged.

The following options of MapLibreMap are not configurable because flutter_map controls the camera: the camera pitch (tilt), the gestures and the initial camera.

Note

The zoom levels of MapLibre are one level lower than the zoom levels of flutter_map (with its default 256px tiles). MapLibreLayer converts the zoom for you. Keep that in mind when you set minZoom and maxZoom of the MapLibreLayer, they use the MapLibre zoom levels. To restrict the camera use the options of FlutterMap.

Use FlutterMap layers inside MapLibre

Wrap each flutter_map layer with a FlutterMapAdapter and add it to the children of MapLibreMap. All gesture inputs are handled by maplibre.

@override
Widget build(BuildContext context) {
  return ml.MapLibreMap(
    onMapCreated: (controller) => _controller = controller,
    options: ml.MapOptions(
      initCamera: ml.CameraUpdate.position(zoom: 3),
      maxPitch: 0, // flutter_map doesn't support camera pitch, disable it here
      style: ml.MapStyle.url('https://tiles.openfreemap.org/styles/liberty'),
    ),
    children: [
      // wrap each of your flutter_map layer with a FlutterMapAdapter widget
      const FlutterMapAdapter(
        child: MarkerLayer(
          markers: [
            Marker(
              point: LatLng(15, 5),
              width: 40,
              height: 40,
              child: Icon(Icons.location_on, color: Colors.red, size: 40),
              alignment: Alignment.topCenter,
            ),
          ],
        ),
      ),
    ],
  );
}

Note

In this example MapOptions, CameraUpdate and MapLibreMap come from package:maplibre/maplibre.dart (imported as ml to avoid name clashes).

Limitations

  • flutter_map can't tilt the camera. MapLibreLayer disables the pitch.
  • MapLibreLayer works with the default Epsg3857 coordinate reference system of FlutterMap only, because MapLibre uses Web Mercator.
  • MapLibre renders vector tiles with native SDKs. Platform support is the same as the maplibre package.

Additional information

Pull requests or bug reports are welcome.

If you need help you can open an issue or join the flutter_map discord server.