Flutter MapLibre GL¶

Note

This documentation is not a comprehensive introduction to Flutter and assumes some familiarity. We would refer you to the official documentation for more info. We have also uploaded a comprehensive example illustrating a full-screen map with annotations, interaction, and clustering.

Don't forget to sign up for a free Stadia Maps account so you can try this on your own device!

Get Started With a Free Account

Flutter MapLibre GL is a Flutter wrapper around MapLibre GL Native and MapLibre GL JS which we recommend for most Flutter users building an iOS/Android app with vector maps.

Quickstart¶

Warning

All mobile and desktop applications involve making requests using an API key. You must take care to secure this, especially if your app reaches end user outside your organization. See our authentication docs for more details.

Note

At the time of this writing, the library is not yet available on pub.dev, which is why we reference the GitHub repo directly.

First, add the library to your pubspec under dependencies.

pubspec.yaml

dependencies:
  ...
  maplibre_gl:
    git:
      url: https://github.com/m0nac0/flutter-maplibre-gl.git
      ref: main

Tip

You can pin to a release branch rather than main for stability. Note that the library is still under fairly active development and has not yet hit a v1.0 release.

Second, add the necessary dependencies to your Podfile.

iOS/Podfile

source 'https://github.com/m0nac0/flutter-maplibre-podspecs.git'

pod 'MapLibre'
pod 'MapLibreAnnotationExtension'

Finally, you're ready to instantiate a MaplibreMap widget and add it to your app! Here is an example of how to use it with a Stadia Maps vector style.

const styleUrl = "https://tiles.stadiamaps.com/styles/alidade_smooth_dark.json";
const apiKey = "YOUR-API-KEY";
MaplibreMap(
  styleString: "$styleUrl?api_key=$apiKey",
  myLocationEnabled: true,
  initialCameraPosition: const CameraPosition(target: LatLng(0.0, 0.0)),
  trackCameraPosition: true,
)

You can browse our map style library for additional vector styles, or create your own. Be sure to register for a free API key.

Flutter MapLibre GL iOS Screenshot

Gotchas¶

Warning

Make sure to test your application thoroughly on all platforms that you target. In our experience, even trivial applications can exhibit differing behavior and/or subtle bugs on one or more platforms.

If you are targeting web, you should additionally make sure to add the MapLibre GL JS script reference in the head section of your index.html.

<head>
    <!-- MapLibre GL JS -->
    <script src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
    <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet" />
</head>

Example Repository¶

We have published a full example repository on GitHub which visualizes a set of earthquake data. This is analogous to the cluster example for MapLibre GL JS.

Next Steps¶

The project's GitHub repo is the authoritative source for documentation and further information. Additionally, browsable API documentation is hosted here (note that it is sometimes a bit slow to load).

And of course, don't forget to sign up for a free Stadia Maps account, so you can try this on your own device!

Get Started With a Free Account