mapbox/mapbox-flutter-patterns
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.
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-flutter-patternsOfficial patterns for integrating the Mapbox Maps SDK for Flutter (mapbox_maps_flutter) on iOS and Android with Dart.
Use this skill when:
MapWidget with camera / style optionsOfficial Resources:
> Web and desktop are not supported — the Flutter SDK targets iOS and Android only.
# pubspec.yaml
dependencies:
mapbox_maps_flutter: ^2.0.0
flutter pub get
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.
ios/Runner.xcworkspace in Xcode.14.0.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.
Add the purpose string to ios/Runner/Info.plist:
<key>NSLocationWhenInUseUsageDescription</key>
<string>Show your location on the map</string>
Add to android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
The recommended pattern is to pass the token via --dart-define at build/run time and set it on MapboxOptions before creating any MapWidget.
flutter run --dart-define=ACCESS_TOKEN=pk.your_token_here
// main.dart
import 'package:flutter/material.dart';
import 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';
const accessToken = String.fromEnvironment('ACCESS_TOKEN');
void main() {
MapboxOptions.setAccessToken(accessToken);
runApp(const MaterialApp(home: MapScreen()));
}
Never hard-code tokens in source. For CI, pass --dart-define=ACCESS_TOKEN=$MAPBOX_ACCESS_TOKEN.
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 Scaffold(
body: MapWidget(
key: const ValueKey('mapWidget'),
cameraOptions: CameraOptions(
center: Point(coordinates: Position(-122.4194, 37.7749)),
zoom: 12,
),
styleUri: MapboxStyles.STANDARD,
),
);
}
}
MapboxMap controllerclass MapScreen extends StatefulWidget {
const MapScreen({super.key});
@override
State<MapScreen> createState() => _MapScreenState();
}
class _MapScreenState extends State<MapScreen> {
MapboxMap? mapboxMap;
void _onMapCreated(MapboxMap controller) {
mapboxMap = controller;
}
@override
Widget build(BuildContext context) {
return MapWidget(
key: const ValueKey('mapWidget'),
onMapCreated: _onMapCreated,
cameraOptions: CameraOptions(
center: Point(coordinates: Position(-122.4194, 37.7749)),
zoom: 12,
),
);
}
}
Use mapboxMap.annotations to create managers for point, circle, polyline, and polygon annotations. Managers are long-lived — create them once and reuse for updates.
import 'package:flutter/services.dart' show rootBundle;
PointAnnotationManager? pointAnnotationManager;
Future<void> _addMarkers(MapboxMap mapboxMap) async {
pointAnnotationManager = await mapboxMap.annotations.createPointAnnotationManager();
final bytes = await rootBundle.load('assets/marker.png');
final imageBytes = bytes.buffer.asUint8List();
final options = <PointAnnotationOptions>[
PointAnnotationOptions(
geometry: Point(coordinates: Position(-122.4194, 37.7749)),
image: imageBytes,
iconSize: 1.2,
),
PointAnnotationOptions(
geometry: Point(coordinates: Position(-122.4094, 37.7849)),
image: imageBytes,
),
];
await pointAnnotationManager!.createMulti(options);
}
Remember to register the asset in pubspec.yaml:
flutter:
assets:
- assets/marker.png
Use manager.tapEvents — this is the current API. addOnPointAnnotationClickListener is deprecated.
tapEvents returns a Cancelable that you store and invoke .cancel() on when the listener is no longer needed:
final Cancelable tapSubscription = pointAnnotationManager!.tapEvents(
onTap: (annotation) {
debugPrint('Tapped annotation ${annotation.id}');
},
);
@override
void dispose() {
tapSubscription.cancel();
super.dispose();
}
The same pattern — returning a Cancelable — exists on every manager's longPressEvents and dragEvents, and across the other annotation types (CircleAnnotationManager.tapEvents, etc.).
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.
Permissions must already be granted (use permission_handler or similar) before enabling the puck.
await mapboxMap.location.updateSettings(LocationComponentSettings(
enabled: true,
puckBearingEnabled: true,
locationPuck: LocationPuck(
locationPuck2D: DefaultLocationPuck2D(),
),
));
// Instant jump
await mapboxMap.setCamera(CameraOptions(
center: Point(coordinates: Position(-80.1263, 25.7845)),
zoom: 14,
));
// Animated fly-to
await mapboxMap.flyTo(
CameraOptions(
center: Point(coordinates: Position(-80.1263, 25.7845)),
zoom: 17,
bearing: 180,
pitch: 30,
),
MapAnimationOptions(duration: 2000),
);
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 calledIf 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.
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.
iOS/Android will not re-read manifests or Info.plist on hot reload. Fully restart the app after editing permissions.
references/annotations.md — Circle, Polyline, Polygon patterns and GeoJSON source/layer recipes.references/platform-setup.md — Deeper iOS/Android setup, token strategies, release signing notes.Take mapbox/mapbox-flutter-patterns from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.