flutter_map_maplibre 0.1.0-pre.2
flutter_map_maplibre: ^0.1.0-pre.2 copied to clipboard
Performant Mapbox Vector Tiles (MVT) support for flutter_map powered by native MapLibre SDKs.
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 aMapLibreMapas a layer inside ofFlutterMap.FlutterMapAdapter: useflutter_maplayers (markers, polylines, ...) inside ofMapLibreMap.

Getting started #
- Add the dependencies to your
pubspec.yamlfile.
dependencies:
flutter_map: ^8.0.0
flutter_map_maplibre: ^0.1.0-pre.2
maplibre: ^0.4.0-pre.2
- Follow the platform specific
setup steps
for the
maplibrepackage:
- 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_mapcan't tilt the camera.MapLibreLayerdisables the pitch.MapLibreLayerworks with the defaultEpsg3857coordinate reference system ofFlutterMaponly, 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.