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 Official Resources: [Flutter Maps Guides](https://docs.mapbox.com/flutter/maps/guides/) [API Reference on pub.dev](https://pub.dev/documentation/mapbox maps flutter/latest/) [Example App](https://github.com/mapbox/mapbox maps flutter/tree/main/example) 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 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. 1. Open ios/Runner.xcworkspace in Xcode. 2. Select the Runner target → General → set Minimum Deployments → iOS to 14.0 . 3. If ios/Podfile exists, update the platform line too: 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 : Step 4: Android permissions Add to android/app/src/main/AndroidManifest.xml : Step 5: Configure the access token The recommended pattern is to pass the token via dart define at build/run time and set it on MapboxOptions before creating any MapWidget . Never hard code tokens in source. For CI, pass dart define=ACCESS TOKEN=$MAPBOX ACCESS TOKEN . Map Initialization Basic map Grab the MapboxMap controller Add Annotations Use mapboxMap.annotations to create managers for point, circle, polyline, and polygon annotations. Managers are long lived — create them once and reuse for updates. Point annotations with a custom image Remember to register the asset in pubspec.yaml : Tap handling 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: 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 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. Camera Control Troubleshooting 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. references/platform setup.md — Deeper iOS/Android setup, token strategies, release signing notes. Additional Resources [Flutter Maps Guides](https://docs.mapbox.com/flutter/maps/guides/) [Markers and Annotations guide](https://docs.mapbox.com/flutter/maps/guides/markers and annotations/) [User Location guide](https://docs.mapbox.com/flutter/maps/guides/user location/) [Example App](https://github.com/mapbox/mapbox maps flutter/tree/main/example)

mapbox-flutter-patterns