Offline Map Caching with Mapbox in Flutter

Introduction

Offline map support is essential for Flutter apps that need to function where connectivity is poor or nonexistent. Mapbox offers a powerful offline tile management API that lets you download, store, and serve map tiles on-device. This tutorial shows you how to integrate Mapbox’s offline caching into your Flutter project, covering setup, region configuration, tile downloads, and error handling.

Mapbox Setup in Flutter

First, add the official Mapbox Flutter plugin to your pubspec.yaml. As of this writing, mapbox_gl supports both Android and iOS.

dependencies:
  flutter:
    sdk: flutter
  mapbox_gl

Next, configure Android and iOS API keys:

• Android: In android/app/src/main/AndroidManifest.xml, add <meta-data android:name="com.mapbox.token" android:value="YOUR_MAPBOX_ACCESS_TOKEN"/> inside <application>.

• iOS: In ios/Runner/Info.plist, add <key>MGLMapboxAccessToken</key><string>YOUR_MAPBOX_ACCESS_TOKEN</string>.

Now import and initialize your MapboxMapController in your widget:

MapboxMap(
  initialCameraPosition: CameraPosition(target: LatLng(37.7749, -122.4194), zoom: 12),
  onMapCreated: (controller) => _mapController = controller,
)

Configuring Offline Regions

Offline regions define the rectangular area and zoom levels you want to cache. Use the OfflineRegionManager from mapbox_gl:

final offlineManager = await OfflineRegionManager.create();
final definition = OfflineRegionDefinition(
  styleURL: MapboxStyles.MAPBOX_STREETS,
  bounds: LatLngBounds(
    southwest: LatLng(37.7034, -122.527),
    northeast: LatLng(37.812, -122.3482),
  ),
  minZoom: 10,
  maxZoom: 16,
  pixelRatio: MediaQuery.of(context).devicePixelRatio,
);
final metadata = {'name': 'SFRegion'};
await offlineManager.createOfflineRegion(definition, metadata);

This snippet sets up an offline region around San Francisco from zoom 10 to 16.

Downloading and Managing Tiles

Once a region is created, you can start the download task and listen for progress updates:

final region = await offlineManager.getRegionByName('SFRegion');
await region.setDownloadState(DownloadState.active);
region.stream.listen((status) {
  final progress = (status.completedResourceCount / status.requiredResourceCount) * 100;
  print('Download progress: ${progress.toStringAsFixed(0)}%');
  if (status.downloadState == DownloadState.complete) {
    print('Offline region ready');
  }
});

Key points: • Call setDownloadState(DownloadState.active) to start. • The requiredResourceCount can initially be -1; wait for it to become positive. • On completion, tiles are cached on-device.

To list and delete cached regions:

final regions = await offlineManager.listOfflineRegions();
await regions[0].delete();  // Delete the first region

Best Practices and Error Handling

• Storage Management: Monitor device storage and limit the number of simultaneous offline regions. Remove unused regions.

• Zoom Layers: Higher zoom levels multiply tile counts exponentially. Cap maxZoom to balance detail vs. size.

• Connectivity Checks: If connectivity drops mid-download, catch exceptions and retry.

try {
  await region.setDownloadState(DownloadState.active);
} catch (e) {
  print('Download error: $e');
  // You might retry or alert the user
}

• Metadata Tags: Store descriptive names and timestamps in metadata for easier region management.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

Mapbox’s offline tile caching in Flutter provides robust offline map experiences. By setting up offline regions, handling downloads, and managing stored tiles, you ensure your users can navigate seamlessly without a network. Follow best practices to optimize storage and handle errors gracefully. Integrate these patterns into your Flutter app to deliver reliable maps anywhere.