Skip to content

Annotation Layers

Annotation layers show your own points, lines and areas on the map. Put them in the MapLibreMap.layers list and change them like any other widget parameter, with setState() or the state management of your choice. The map adds, updates and removes only what changed.

Layer Geometry Built on
CircleLayer Point CircleStyleLayer
MarkerLayer Point SymbolStyleLayer
PolygonLayer Polygon FillStyleLayer
PolylineLayer LineString LineStyleLayer

Flutter widgets on the map go into a WidgetLayer. For large or frequently changing data, add a source and a style layer to the style instead.

Circles

Circles

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
@override
Widget build(BuildContext context) {
  return MapLibreMap(
    options: MapOptions(initCamera: .position(center: Geographic(lon: 9.17, lat: 47.68), zoom: 7)),
    layers: [
      CircleLayer(
        points: const [
          Feature(geometry: Point(Geographic(lon: 9.17, lat: 47.68))),
          Feature(geometry: Point(Geographic(lon: 9.17, lat: 48))),
          Feature(geometry: Point(Geographic(lon: 9, lat: 48))),
          Feature(geometry: Point(Geographic(lon: 9.5, lat: 48))),
        ],
        color: .literal(Colors.orange.withValues(alpha: 0.5)),
        radius: const .literal(20),
        strokeColor: const .literal(Colors.red),
        strokeWidth: const .literal(2),
      ),
    ],
  );
}

See the example app.

Markers

Markers

Markers show an icon, a label or both. The icon of the layer is its image, which the map adds to the style for it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
final _points = <Feature<Point>>[
  const Feature(geometry: Point(Geographic(lon: 9.17, lat: 47.68))),
  const Feature(geometry: Point(Geographic(lon: 9, lat: 48))),
];

@override
Widget build(BuildContext context) {
  return MapLibreMap(
    options: MapOptions(initCamera: .position(center: Geographic(lon: 9.17, lat: 47.68), zoom: 7)),
    // add a marker where the user taps
    onClick: (event) =>
        setState(() => _points.add(Feature(geometry: Point(event.point)))),
    layers: [
      MarkerLayer(
        points: _points,
        icon: const .iconData(Icons.location_on, color: Colors.red),
        textField: const .literal('Marker'),
        textAllowOverlap: const .literal(true),
        iconAnchor: const .literal(IconAnchor.bottom),
        textOffset: const .literal(Offset(0, 1)),
      ),
    ],
  );
}

A MarkerIcon is one of:

Icon Image
.iconData(Icons.place, color:, size:) An icon font glyph, size logical pixels large (48)
.asset('assets/pin.png', pixelRatio:) A Flutter asset
.bytes(pngBytes, pixelRatio:) Encoded image bytes, such as a PNG
.provider(NetworkImage(url)) Any ImageProvider, at the scale of the image it loads
.named('pin') An image the style already has, from its sprite or addImage
.expression(Expression.get('icon').asString()) Per feature, an image the style already has

For .iconData(), .asset(), .bytes() and .provider(), the map adds each image once, shares it between the layers with an equal icon, removes it once no layer shows it, and adds it again when another style loads. Images that .named() and .expression() refer to come from the style, so add an image of your own again with addImage after another style loads.

See the example app.

Polygons

Polygons

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@override
Widget build(BuildContext context) {
  return MapLibreMap(
    options: MapOptions(initCamera: .position(center: Geographic(lon: 9.17, lat: 47.68), zoom: 7)),
    layers: [
      PolygonLayer(
        polygons: [
          Feature(
            geometry: Polygon.from(const [
              [
                Geographic(lon: 8.2013, lat: 48.1074),
                Geographic(lon: 8.8853, lat: 48.0943),
                Geographic(lon: 8.7597, lat: 47.6933),
                Geographic(lon: 9.6320, lat: 48.0893),
                Geographic(lon: 8.6854, lat: 48.4538),
                Geographic(lon: 8.2013, lat: 48.1074),
              ],
            ]),
          ),
        ],
        color: .literal(Colors.lightBlueAccent.withValues(alpha: 0.6)),
        outlineColor: const .literal(Colors.blue),
      ),
    ],
  );
}

See the example app.

Polylines

Polylines

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@override
Widget build(BuildContext context) {
  return MapLibreMap(
    options: MapOptions(initCamera: .position(center: Geographic(lon: 9.17, lat: 47.68), zoom: 7)),
    layers: [
      PolylineLayer(
        polylines: [
          Feature(
            geometry: LineString.from(const [
              Geographic(lon: 9.17, lat: 47.68),
              Geographic(lon: 9.5, lat: 48),
              Geographic(lon: 9, lat: 48),
            ]),
          ),
        ],
        color: const .literal(Colors.red),
        width: const .literal(4),
        blur: const .literal(3),
        dashArray: const .literal([5, 5]),
      ),
    ],
  );
}

See the example app.

Ids

Every annotation layer is a style layer with a GeoJSON source of the same id. Set id to name them:

CircleLayer(id: 'stops', points: stops)

The id must not be in use by a layer or source of the style, or by another layer of the list, and must not start with maplibre-, which the map uses. It also tells a rebuild which layer is which, like a Key of a widget: a layer with an id keeps its style layer and source wherever it moves in the list. Layers without an id match the next layer of the same type without an id, in the order of the list.

Read and query the style layers by these ids, for example with queryRenderedFeatures(layerIds: ['stops']). Change them only through MapLibreMap.layers: style.layers.remove() and .move() fail for them, and their setters warn in debug builds, as the next rebuild would undo the change. The same goes for their sources: style.sources.updateGeoJsonData() warns for them.

Order and anchors

Layers with the same anchor draw in the order of the list, the first at the bottom, like the children of a Stack. A reordered list moves the style layers. By default the annotation layers go on top of the style. anchor places a layer elsewhere, and layers with different anchors draw where their anchors put them:

PolylineLayer(
  polylines: routes,
  // below the labels of the style
  anchor: const .below('road-label'),
)
Anchor Place
.top() Above every layer of the style (default)
.bottom() Below every layer of the style
.below('layerId') Right below the style layer layerId
.above('layerId') Right above the style layer layerId

Layers with the same anchor keep the order of the list among themselves. .below() and .above() name a layer of the style, not one of the list. If the current style has no such layer, the layer goes on top and debug builds print a warning. The layers keep their place when the app adds, moves or removes style layers later, for example once a layer named by an anchor is added.

The layers, their sources and their icons stay on the map when another style loads.

Style each feature

Every style parameter is an expression, so it can depend on the properties of each feature:

CircleLayer(
  points: points,
  radius: .get('size').asNumber(),
  color: .get('color').convertToColor(),
)

A map can show any number of annotation layers, each with its own style. For properties that the annotation layers don't have, use the style layer they are built on.

Interaction