Get Started
The Mapbox Maps SDK for Flutter 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.
Most core APIs are supported on web, but some features are still working toward full parity with iOS and Android.
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
Your Flutter app reads the access token from the environment at build time, not from a string in your source code. This keeps the token out of version control and lets you use a different token for each machine or environment.
A good practice is to store the token in a shell environment variable on your development machine, so you don't have to type or paste it every time you build or run the app. Run one of the following commands to add it to your shell profile and load it into your current terminal session. Replace <YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN>, including the angle brackets, with your own public access token before running the command.
If you use zsh (the default shell on macOS):
$echo 'export MAPBOX_ACCESS_TOKEN="<YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN>"' >> ~/.zshrc && source ~/.zshrc
If you use bash:
$echo 'export MAPBOX_ACCESS_TOKEN="<YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN>"' >> ~/.bashrc && source ~/.bashrc
Then, pass the value of that variable to Flutter with the --dart-define flag when running flutter build or flutter run:
$flutter build <platform> --dart-define=ACCESS_TOKEN="$MAPBOX_ACCESS_TOKEN"
$flutter run --dart-define=ACCESS_TOKEN="$MAPBOX_ACCESS_TOKEN"
If you use an editor such as Visual Studio Code or Android Studio, you can configure a launch or run configuration to pass the same --dart-define argument automatically every time you start the app from the editor. See the Visual Studio Code Flutter documentation on passing arguments and the launch.json reference for how to set this up, or the Android Studio run configuration documentation if you use that IDE instead.
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, add the dependency to the pubspec.yaml:
dependencies:
mapbox_maps_flutter: ^3.0.0
Then fetch the package:
$flutter pub get
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.