mapbox_maps_flutter

Flutter plugin for Mapbox Maps. Provides interactive, customizable vector maps for Android, iOS, and Web.

This is the app-facing package. It endorses:

Requirements

  • Flutter 3.38.1 / Dart 3.10.0 or higher
  • Android: minSdk 21 or higher
  • iOS: 14 or higher
  • Web: Mapbox GL JS 3.25.0 or higher

Installation

1. Add the dependency

dependencies:
  mapbox_maps_flutter: ^3.0.0-alpha.1

Then run flutter pub get.

2. Configure your access token

Set a Mapbox access token once at app startup, before creating any MapWidget:

import 'package:flutter/widgets.dart';
import 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  MapboxOptions.setAccessToken(const String.fromEnvironment('ACCESS_TOKEN'));
  runApp(const MyApp());
}

Pass the token via --dart-define:

flutter run --dart-define=ACCESS_TOKEN=<your token>

See the access token docs for how to provision tokens and scopes.

3. Platform setup

Android — add to android/app/src/main/AndroidManifest.xml if you use the location component:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS — add to ios/Runner/Info.plist if you use the location component:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Explain why your app needs location access.</string>

Web — load Mapbox GL JS in web/index.html inside <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>

4. Add a map

import 'package:flutter/material.dart';
import 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';

class MapScreen extends StatelessWidget {
  const MapScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return const Scaffold(body: MapWidget());
  }
}

For the full API surface — camera, gestures, styles, sources and layers, annotations, viewport, location component — see the platform package READMEs linked above.

Libraries

mapbox_maps_flutter