Labsco
mapbox logo

mapbox-flutter-patterns

★ 68

by mapbox · part of mapbox/mapbox-agent-skills

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.

🔌 This skill ships inside the Mapbox Agent Skills plugin — install the plugin and you also get an MCP server.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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:

Web and desktop are not supported — the Flutter SDK targets iOS and Android only.

Map Initialization

Basic 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 Scaffold(
      body: MapWidget(
        key: const ValueKey('mapWidget'),
        cameraOptions: CameraOptions(
          center: Point(coordinates: Position(-122.4194, 37.7749)),
          zoom: 12,
        ),
        styleUri: MapboxStyles.STANDARD,
      ),
    );
  }
}

Grab the MapboxMap controller

class 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,
      ),
    );
  }
}

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

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

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:

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.).

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.

await mapboxMap.location.updateSettings(LocationComponentSettings(
  enabled: true,
  puckBearingEnabled: true,
  locationPuck: LocationPuck(
    locationPuck2D: DefaultLocationPuck2D(),
  ),
));

Camera Control

// 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),
);

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