Official integration patterns for the Mapbox Maps Flutter SDK. Covers installation, iOS/Android platform setup, access token configuration, MapWidget initialization, camera control, annotations with tap handling, user location, and loading GeoJSON. Based on official Mapbox documentation.
Official integration patterns for the Mapbox Maps Flutter SDK. Covers installation, iOS/Android platform setup, access token configuration, MapWidget initialization, camera control, annotations with tap handling, user location, and loading GeoJSON. Based on official Mapbox documentation.
Mapbox Flutter Integration Patterns
Official patterns for integrating the Mapbox Maps SDK for Flutter (mapbox_maps_flutter) on iOS and Android with Dart.
Use this skill when:
Installing and configuring mapbox_maps_flutter in a Flutter app
Setting the Mapbox access token the right way
Initializing a MapWidget with camera / style options
Adding annotations (points, circles, lines, polygons) and handling taps
Showing the user location puck
Loading GeoJSON from app assets
Troubleshooting iOS build failures after adding Mapbox
Web and desktop are not supported — the Flutter SDK targets iOS and Android only.
Installation & Setup
Requirements
Flutter SDK 3.22.3 / Dart 3.4.4+
iOS: deployment target 14.0 or higher
Android: minSdk 21 or higher
Free Mapbox account
Step 1: Add the dependency
# pubspec.yamldependencies:mapbox_maps_flutter:
^2.0.0
flutter pub get
Step 2: Bump the iOS deployment target to 14.0 (required)
This is the single most common cause of iOS build failures after adding Mapbox. The Flutter SDK requires iOS 14.0 and will not compile on the Flutter default.
Open ios/Runner.xcworkspace in Xcode.
Select the Runner target → General → set Minimum Deployments → iOS to 14.0.
If ios/Podfile exists, update the platform line too:
# ios/Podfile
platform :ios, '14.0'
You do not need to worry about CocoaPods vs Swift Package Manager — mapbox_maps_flutter supports both and Flutter picks whichever your app is configured for.
Step 3: iOS location permission
Add the purpose string to ios/Runner/Info.plist:
<key>NSLocationWhenInUseUsageDescription</key><string>Show your location on the map</string>
Use mapboxMap.annotations to create managers for point, circle, polyline, and polygon annotations. Managers are long-lived — create them once and reuse for updates.
The same pattern — returning a Cancelable — exists on every manager's longPressEvents and dragEvents, and across the other annotation types (CircleAnnotationManager.tapEvents, etc.).
Load annotations from GeoJSON
import 'dart:convert';
import 'package:flutter/services.dart' show rootBundle;
Future<void> _loadGeoJson(MapboxMap mapboxMap) async {
final raw = await rootBundle.loadString('assets/coffee_shops.geojson');
final geo = jsonDecode(raw) as Map<String, dynamic>;
final features = (geo['features'] as List).cast<Map<String, dynamic>>();
final manager = await mapboxMap.annotations.createPointAnnotationManager();
final icon = (await rootBundle.load('assets/coffee.png')).buffer.asUint8List();
final options = features.map((feature) {
final coords = feature['geometry']['coordinates'] as List;
return PointAnnotationOptions(
geometry: Point(coordinates: Position(coords[0] as double, coords[1] as double)),
image: icon,
);
}).toList();
await manager.createMulti(options);
}
For thousands of features use a style layer (GeoJsonSource + SymbolLayer) instead of annotations.
Show User Location
Permissions must already be granted (use permission_handler or similar) before enabling the puck.
iOS build fails with "platform is lower than deployment target"
The Flutter default iOS deployment target is lower than Mapbox's minimum (iOS 14). Set Minimum Deployments → iOS to 14.0 on the Runner target in Xcode. If the project has an ios/Podfile, also set platform :ios, '14.0' there and re-run pod install.
setAccessToken not called
If you forget to call MapboxOptions.setAccessToken before creating a MapWidget, the map will load with a blank grid. Always call it in main() before runApp.
Annotation tap handler not firing
Make sure you're using manager.tapEvents(onTap: ...) — addOnPointAnnotationClickListener is deprecated. Also confirm the MapboxMap controller is captured via onMapCreated before you create the annotation manager.
Hot reload after permissions change
iOS/Android will not re-read manifests or Info.plist on hot reload. Fully restart the app after editing permissions.
Reference Files
references/annotations.md — Circle, Polyline, Polygon patterns and GeoJSON source/layer recipes.
