Migrate from flutter_map

flutter_map and maplibre both take their layers as widget parameters and update with setState(), so the structure of your map code stays the same. The difference is the renderer: flutter_map draws tiles and layers with Flutter in Dart, while maplibre renders vector and raster tiles with MapLibre on the GPU and shows the result in a Flutter Texture (an HTML element on web). Vector tiles, labels, large data, 3D extrusions, offline regions and the user location are built in instead of plugins.

Both packages have a MapOptions, MapController, MarkerLayer, PolylineLayer, PolygonLayer and CircleLayer, so replace the import in each file instead of using both.

1. Replace the dependency

flutter pub remove flutter_map latlong2
flutter pub add maplibre:^0.4.0-pre.2

Also remove the plugins that maplibre covers, such as vector_map_tiles, flutter_map_tile_caching, flutter_map_location_marker and flutter_map_marker_cluster. Then follow Platform setup.

2. Map data

flutter_map gets its map from TileLayers. maplibre loads a map style, which names the tile sources and how to draw them. Use the style of a vector tile provider, or keep your raster tiles with a style of one raster source:

FlutterMap(
  options: const MapOptions(
    initialCenter: LatLng(47.68, 9.17),
    initialZoom: 7,
  ),
  children: [
    TileLayer(
      urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
      userAgentPackageName: 'com.example.app',
    ),
    RichAttributionWidget(
      attributions: [TextSourceAttribution('OpenStreetMap contributors')],
    ),
  ],
)

MapLibreMap(
  options: MapOptions(
    style: MapStyle.json('''
      {
        "version": 8,
        "sources": {
          "osm": {
            "type": "raster",
            "tiles": ["https://tile.openstreetmap.org/{z}/{x}/{y}.png"],
            "tileSize": 256,
            "attribution": "© <a href='https://www.openstreetmap.org/copyright'>OpenStreetMap contributors</a>"
          }
        },
        "layers": [{"id": "osm", "type": "raster", "source": "osm"}]
      }
    '''),
    initCamera: .position(
      center: Geographic(lon: 9.17, lat: 47.68),
      zoom: 7,
    ),
  ),
  // OpenStreetMap requires an attribution that stays visible.
  children: const [SourceAttribution(keepExpanded: true)],
)

For vector tiles, use a style URL instead, for example MapStyle.url('https://tiles.openfreemap.org/styles/liberty'). Additional tile layers become sources and style layers, and WMS or other overlays become a RasterSource.

3. Map options and controller

Coordinates are geobase Geographic(lon: …, lat: …) instead of latlong2's LatLng(lat, lng), and bounds are a GeoBox instead of LatLngBounds.

flutter_map animates with plugins such as flutter_map_animations; maplibre has controller.animateCamera with CameraAnimation.ease and .fly. Unlike flutter_map, the map can also pitch, so MapOptions has minPitch and maxPitch. See Map & Camera.

4. Layers

Annotation layers go into MapLibreMap.layers, not children. They take geobase Features and style each one with expressions, instead of an object with a style per marker or line.

PolylineLayer(
  polylines: [
    Polyline(
      points: const [LatLng(47.68, 9.17), LatLng(48, 9.5)],
      color: Colors.red,
      strokeWidth: 4,
    ),
  ],
)

PolylineLayer(
  polylines: [
    Feature(
      geometry: LineString.from(const [
        Geographic(lon: 9.17, lat: 47.68),
        Geographic(lon: 9.5, lat: 48),
      ]),
    ),
  ],
  color: const .literal(Colors.red),
  width: const .literal(4),
)

A MarkerLayer of the map draws thousands of points without building a widget for each. Prefer it over a WidgetLayer when the markers are icons or text. For large data, a source with style layers skips comparing the layer lists on rebuilds.

5. Overlays and plugins

Widgets in MapLibreMap.children are drawn over the map, like non-layer children in flutter_map. They can read the map with MapController.of(context), MapOptions.of(context) and CameraPosition.of(context), as plugins read MapCamera.of(context).

6. What changes for your app

• The map is drawn by MapLibre, not by Flutter widgets, so painting the map with your own widgets or CustomPainters per tile is not possible. Draw over it with children, or style it with layers.
• Styles and layers follow the MapLibre style spec, so you can edit them in Maputnik and reuse them in MapLibre apps on other platforms.