Plugins
A plugin is a widget in the children of MapLibreMap. Plugins can come
from your app or from a package, and every widget in children can do what
a plugin does.
MapLibreMap(
layers: [/* the app's own layers */],
children: [
const SourceAttribution(),
if (measuring) const MeasureLine(),
],
)
Adding a plugin to children turns it on and removing it turns it off,
along with everything it added to the map.
What a plugin can do
Read the map
Every widget below the map can call these:
| Call | Returns | The widget rebuilds when |
|---|---|---|
MapController.of(context) / maybeOf |
The controller: camera moves, queries, the style | The controller, options or style change, or the map pauses or resumes rendering |
CameraPosition.of(context) / maybeOf |
The current camera | The camera moves |
MapOptions.of(context) / maybeOf |
The MapLibreMap.options |
The options change |
StyleController.of(context) / maybeOf |
The loaded style: layers, sources, attributions | A style loads, layers or sources come, go or move, or the attributions change |
Only CameraPosition.of rebuilds the widget while the camera moves. Use it
when a widget shows something that depends on the camera, such as a
position on the screen. Use MapController.of alone for a widget that only
calls the controller, such as a button.
StyleController.of suits a widget that lists what the style has, such as
a layer switcher or a legend. It doesn't rebuild when the properties of a
layer or the data of a source change, as apps change those every frame. Code
outside of build can listen to the StyleController, its layers or its
sources instead.
Draw over the map
A plugin builds Flutter widgets that show above the map, like any other
widget in children. MapController.toScreenLocations turns coordinates
into positions on the screen.
Add layers, listen to events and limit movements
The MapPlugin widget takes the same layers and callbacks as MapLibreMap:
class MeasureLine extends StatefulWidget {
const MeasureLine({super.key});
@override
State<MeasureLine> createState() => _MeasureLineState();
}
class _MeasureLineState extends State<MeasureLine> {
final _points = <Geographic>[];
@override
Widget build(BuildContext context) => MapPlugin(
// Adds a point at every tap.
onClick: (event) => setState(() => _points.add(event.point)),
// Shown above the layers of MapLibreMap.
layers: [
if (_points.length > 1)
PolylineLayer(polylines: [Feature(geometry: LineString.from(_points))]),
CircleLayer(
points: [for (final point in _points) Feature(geometry: Point(point))],
),
],
// The user can't rotate the map while the plugin is shown.
movements: const MapMovements(rotate: false),
// A Flutter widget over the map, laid out like a widget in children.
child: const Align(alignment: Alignment.topCenter, child: Text('Tap to measure')),
);
}
The map combines every MapPlugin with its own parameters:
- Layers show above
MapLibreMap.layers, the layers of later plugins above those of earlier ones. They stay on the map when the style changes, and theironClick,onEnter,onLeaveanddraggablework as on annotation layers. - Taps, clicks, drags and mouse moves go to the plugins under the
pointer first, the topmost first, and then to the callbacks of
MapLibreMap. Every callback gets the event, so a plugin can't keep it from your app. A plugin can callpreventDefaulton a double click or the start of a drag to stop the map from zooming or panning, and the callbacks after it see that indefaultPrevented. - Other events, such as camera moves, style loads and errors, go to every
plugin and then to
MapLibreMap. - Movements and gestures of a plugin can only turn things off: the
user's gestures move the map only the ways that
MapOptionsand every plugin allow. Camera calls, such asanimateCamera, are not limited.
A MapPlugin fills the map and never takes a pointer itself, so the map
still gets the pointers its child lets through. Wrap it in a Positioned
to receive the taps of only a part of the map.
Share a corner with other widgets
Wrap a plugin's button in a MapAlignItem. Alone, it places the button at
its own alignment. Inside a MapAlign, the group places it next to the
built-in widgets without overlapping. See
User Interface.
Split your map into plugins
Plugins aren't only for packages. As a map screen grows, its
MapLibreMap collects the layers, callbacks and state of every feature on
it. Move each feature into a plugin of its own instead, and the screen only
lists them:
MapLibreMap(
options: MapOptions(style: .url(styleUrl)),
children: [
const MapControlButtons(),
StopsPlugin(stops: stops, onSelect: (stop) => setState(() => selected = stop)),
if (selected != null) SelectedStopPlugin(stop: selected!),
if (measuring) const MeasureLine(),
],
)
Each plugin keeps what belongs to its feature together:
- Its state, layers and callbacks live in one widget, not spread over the screen. A tap handler of one feature can't break another.
- Turning a feature on and off is an
ifinchildren. Removing the plugin removes its layers and callbacks and lifts its movement limits. - Features stay independent. Each plugin reads the map through
MapController.ofandCameraPosition.of, so it works on every map it is put on, and can move to a package of its own later.
Keep a layer or callback on MapLibreMap when it belongs to the screen as a
whole, such as the base data the screen is about.
Packages that extend maplibre
| Package | What it does |
|---|---|
| maplibre_geolocator | Turns the positions of geolocator into the location stream of the UserLocationLayer plugin. |
| flutter_map_maplibre | Shows flutter_map layers on a maplibre map, or a maplibre map as a vector layer in flutter_map. |
Built a plugin or another package for maplibre? Open a pull request to add it here.