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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | |
See the example app.
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 | |
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
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 | |
See the example app.
Polylines
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | |
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
- Click and Hover: react to taps and the mouse on features.
- Drag: let the user move features.