Get Started v3
The Mapbox Maps SDK for Flutter v3 brings web support alongside iOS and Android, letting you ship the same Flutter map code to all three platforms. Before starting to develop your application, you'll need to configure your credentials and add the SDK as a dependency to your Flutter project.
Maps SDK for Flutter v3 is an MVP release. All v2 features are fully available on iOS and Android, but the web platform is still working toward feature parity.
Configure credentials
The SDK requires a public access token from your Mapbox account to access Mapbox services. If you don't already have one, follow the access tokens guide to create or copy a public token from your account.
You should not expose this access token in publicly-accessible source code where unauthorized users might find it. Instead, you should store it somewhere safe on your computer and make sure it is only added when your app is compiled.
Configure your Mapbox access token
It's a good practice to retrieve your Mapbox access token from some external source. You can then pass your token to the environment when building, running, or launching the Flutter app.
You can pass the public access token in using the --dart-define flag when running flutter build or flutter run on the command line:
$flutter build <platform> --dart-define=ACCESS_TOKEN=YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN
$flutter run --dart-define=ACCESS_TOKEN=YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN
If you are using Visual Studio Code, you can configure launch.json to add the --dart-define argument so it is included each time the app is launched.
{
"configurations": [
{
"name": "Flutter",
"request": "launch",
"type": "dart",
"program": "lib/main.dart",
"args": [
"--dart-define",
"ACCESS_TOKEN=YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN"
]
}
]
}
Then, retrieve the token from the environment in the application and set it via MapboxOptions:
...
String accessToken = String.fromEnvironment("ACCESS_TOKEN");
MapboxOptions.setAccessToken(accessToken);
...
Add the dependency
To use the Maps SDK for Flutter v3, add the dependency to the pubspec.yaml:
...
dependencies:
mapbox_maps_flutter: ^3.0.0-alpha.1
...
Then fetch the package:
$flutter pub get
iOS and Android don't require any additional configuration — the plugin handles the native dependencies for you on the first flutter run.
Configure web
The web platform is the only one that needs additional setup. To run your app in a browser, add the Mapbox GL JS script and stylesheet to your project's web/index.html. Maps SDK for Flutter v3 requires Mapbox GL JS version 3.25.0 or later:
<head>
...
<link
href="https://api.mapbox.com/mapbox-gl-js/v3.25.0/mapbox-gl.css"
rel="stylesheet"
/>
<script src="https://api.mapbox.com/mapbox-gl-js/v3.25.0/mapbox-gl.js"></script>
...
</head>
Learn how Mapbox GL JS is loaded in the browser, including CSP and bundling considerations that also apply to the web build of Maps SDK for Flutter v3.
Add a map
Import the mapbox_maps_flutter library and add a MapWidget. The same widget renders on iOS, Android, and web:
import 'package:flutter/material.dart';
import 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
// Pass your access token to MapboxOptions so you can load a map
String accessToken = const String.fromEnvironment("ACCESS_TOKEN");
MapboxOptions.setAccessToken(accessToken);
// Define the initial viewport for the map
final viewport = CameraViewportState(
center: Point(coordinates: Position(-98.0, 39.5)),
zoom: 2,
bearing: 0,
pitch: 0,
);
runApp(MaterialApp(home: MapWidget(
viewport: viewport,
)));
}
Launch your app on iOS, Android, or in a browser, and you'll see a full-screen globe centered on North America. You can move and zoom the map using touch gestures on mobile or mouse and trackpad gestures on web. As a next step, consider adding Markers and Annotations or changing the map style.