Skip to main content

Get Started

Additional Developer Resources

Before starting to develop your application with the Mapbox Maps SDK, you'll need to configure your credentials and add the SDK as a dependency to your Flutter project.

Configure credentials​

Before installing the SDK, you will need to grab a public access token.

The SDK requires a public access token from your Mapbox account to access Mapbox services. To grab your access token you will need to do the following:

  1. If you haven't done so already, sign up for a Mapbox account and log into it by clicking the buttons in the top right corner of your browser or going to the sign up page.

  2. Go to your account's tokens page

  3. Click the Create a token button to create a new public token or copy your default public token.

  • Creating a new token is the recommended option. To create a new token, you will need to do the following on the Create an access token page:
    • Name your token something relevant to its usage.
    • Skip the Scope and URL sections, the default settings will suit the needs of this tutorial.
    • Scroll down and click the blue Create Token at the bottom of the page.

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 they're 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_MAPBOX_ACCESS_TOKEN

If you are using Visual Studio Code, you can configure launch.json to add the --dart-define argument and each time the app is launched.

.vscode/launch.json
{
    "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:

main.dart
...
String ACCESS_TOKEN = String.fromEnvironment("ACCESS_TOKEN");
MapboxOptions.setAccessToken(ACCESS_TOKEN);
...
GUIDE
Access token best practices

Learn how to keep access tokens private in mobile apps.

Add the dependency​

To use the Maps SDK for Flutter, add the git dependency to the pubspec.yaml:

pubspec.yaml
...
dependencies:
  mapbox_maps_flutter: ^2.0.0
...

Add a map​

Import the mapbox_maps_flutter library and add a map:

main.dart
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 ACCESS_TOKEN = const String.fromEnvironment("ACCESS_TOKEN");
  MapboxOptions.setAccessToken(ACCESS_TOKEN);

  // Define options for your camera
  CameraOptions camera = CameraOptions(
    center: Point(coordinates: Position(-98.0, 39.5)),
    zoom: 2,
    bearing: 0,
    pitch: 0);

  // Run your application, passing your CameraOptions to the MapWidget
  runApp(MaterialApp(home: MapWidget(
    cameraOptions: camera,
  )));
}

Launch your app for iOS or Android, and you'll see a full-screen globe centered on North America in your device emulator. You can move and zoom the map using touch gestures. As a next step, consider adding Markers and Annotations or changing the map style.

iOS
Android
Additional Developer Resources
Was this page helpful?