Offline Regions

Offline regions allow users to download a geographic area and use the map without internet access. The map tiles, fonts, and sprites are all stored on-device.

How it works

flowchart TD
    APP["Your app"] --> CALL["downloadOfflineRegion(<br/>definition, onEvent)"]
    CALL --> BG["MapLibre Native downloads<br/>tiles in the background"]
    BG --> EV["onEvent(status)<br/>called periodically<br/><small>completed / required count<br/>InProgress · Success · Error</small>"]
    BG --> CACHE["Tiles stored in MapLibre's<br/>SQLite cache on device"]

    classDef emphasis fill:#1f6feb,stroke:#1a5fd0,color:#fff;
    class APP emphasis

Once downloaded, the map works offline automatically; no code change needed. When a region is in the cache and the device is offline, MapLibre serves tiles from the local store.

Step 1: Define the region

OfflineRegionDefinition describes what to download:

import 'package:maplibre_gl/maplibre_gl.dart';

final definition = OfflineRegionDefinition(
  bounds: LatLngBounds(
    southwest: const LatLng(48.7, 2.2),  // Paris area
    northeast: const LatLng(49.0, 2.5),
  ),
  minZoom: 10.0,   // download from zoom 10
  maxZoom: 16.0,   // to zoom 16 (street level)
  mapStyleUrl: MapLibreStyles.openfreemapLiberty,
  includeIdeographs: false,  // set true for CJK character support
);

Step 2: Download with a progress callback

import 'package:flutter/foundation.dart'; // for kIsWeb

Future<void> downloadRegion() async {
  if (kIsWeb) return; // offline not supported on web

  final region = await downloadOfflineRegion(
    definition,
    metadata: {'name': 'Paris Center'}, // arbitrary metadata
    onEvent: (DownloadRegionStatus status) {
      if (status is InProgress) {
        final progress = status.requiredResourceCount > 0
            ? status.completedResourceCount / status.requiredResourceCount
            : 0.0;
        setState(() => _progress = progress);
      } else if (status is Success) {
        print('Download complete! Region ID: ${region.id}');
      } else if (status is Error) {
        print('Download failed: ${status.cause.message}');
      }
    },
  );
}

onEvent is called with a DownloadRegionStatus, which comes in three shapes: InProgress while tiles are arriving (it carries the resource counts and byte total), Success once the region is fully downloaded, and Error with the underlying cause if the download fails. Switch on the type rather than reading a state field.

downloadOfflineRegion returns an OfflineRegion object with the assigned id. Store this ID if you need to delete the region later.

metadata is stored as jsonEncode writes it, so a Uint8List comes back as a list of numbers.

Download events reach only the root isolate. In a background isolate, passing onEvent throws an UnsupportedError: leave it out and follow the download with getOfflineRegionStatus.

Step 3: Track progress in UI

double _progress = 0.0;
bool _isDownloading = false;

// In your build():
if (_isDownloading)
  LinearProgressIndicator(value: _progress)
else
  ElevatedButton(
    onPressed: _startDownload,
    child: const Text('Download for offline'),
  )

OfflineRegionStatus fields

List downloaded regions

final List<OfflineRegion> regions = await getListOfRegions();

for (final region in regions) {
  print('Region ${region.id}: ${region.metadata}');
  print('  Bounds: ${region.definition.bounds}');
  print('  Zooms: ${region.definition.minZoom} - ${region.definition.maxZoom}');
}

Use this to show users what they've downloaded and offer delete options.

Check region status

final status = await getOfflineRegionStatus(region.id);
print('Downloaded: ${status.completedResourceCount} tiles');
print('Complete: ${status.isComplete}');

Pause and resume a download

await pauseOfflineRegionDownload(region.id);
// Later, also after the app restarted:
await resumeOfflineRegionDownload(region.id);

A region paused before the app restarted resumes too. No onEvent reports its progress then: read it with getOfflineRegionStatus. A complete region is left as it is.

Delete a region

await deleteOfflineRegion(region.id);

Frees the storage on device. If the user goes offline after deletion, those tiles are no longer available.

Move regions between devices

Offline regions live in a single SQLite database on the device. You can copy that database to another device and merge its regions into the local store, so a region downloaded once can be reused elsewhere without downloading again.

flowchart LR
    A["Device A<br/>download regions"] --> EXP["exportOfflineDatabase(path)<br/>share the .db"]
    EXP --> FILE[(".db file")]
    FILE --> MRG["Device B<br/>mergeOfflineRegions(path)"]
    MRG --> B["Device B<br/>regions available offline"]

    classDef emphasis fill:#1f6feb,stroke:#1a5fd0,color:#fff;
    class A,B emphasis

Export the database

exportOfflineDatabase(destinationPath) writes a copy of the offline database to a location you choose. You pass the full destination file path (folder + file name); the function writes the copy there and returns that same path, or null if nothing has been downloaded yet. It also copies the SQLite -wal/-shm sidecars, so the exported file is consistent.

import 'package:path_provider/path_provider.dart';

Future<String?> exportForSharing() async {
  if (kIsWeb) return null; // offline not supported on web

  final tmp = await getTemporaryDirectory();
  // You decide where the copy goes: here, a temp file called offline_export.db.
  final savedPath = await exportOfflineDatabase('${tmp.path}/offline_export.db');
  // savedPath == '${tmp.path}/offline_export.db', or null if nothing downloaded.
  return savedPath;
}

Then hand savedPath to a share sheet, upload it, or copy it elsewhere.

If you only need the live database's location (for example to copy it yourself), use getOfflineDatabasePath(), which returns its absolute path or null.

Merge a database

mergeOfflineRegions(path) imports every region contained in an external database into the local store and returns the merged regions.

Future<void> importOfflineDatabase(String path) async {
  if (kIsWeb) return; // offline not supported on web

  final List<OfflineRegion> merged = await mergeOfflineRegions(path);
  print('Merged ${merged.length} region(s)');
}

Databases produced by external tools (for example maplibre-native's offline.cpp) can also be merged; regions without Flutter-assigned metadata are imported with an empty metadata map and a stable, derived ID. A file the app can only read, such as one in the app bundle, is merged from a temporary copy.

Storage considerations

• Tiles are stored in MapLibre's SQLite database on device
• Android: stored in the app's internal storage
• Typical sizes: city center at zoom 10–15 ≈ 20–100 MB

Limit the ambient cache

The same database also holds the ambient cache: the tiles, fonts and sprites the map keeps from ordinary browsing, so a recently viewed area still renders through a short loss of connectivity. The native SDKs cap it at 50 MB. To pick a different cap, call setMaximumAmbientCacheSize with a size in bytes before the first map is created:

// Keep at most 20 MB of browsed tiles on disk.
await setMaximumAmbientCacheSize(20 * 1024 * 1024);

Offline regions do not count towards the limit and are never evicted by it. Passing 0 disables ambient caching. If the cache is already over the new limit, the SDK trims it immediately, which can take a moment on a large database. Not available on web, which has no ambient cache.

Errors

The offline calls fail with a PlatformException whose code is the same on Android and iOS. The codes of the other calls are in Errors.

A download that stops before it completes calls onEvent with an Error whose cause.code says why:

try {
  await deleteOfflineRegion(id);
} on PlatformException catch (e) {
  // Deleted already, for example from another screen.
  if (e.code != 'REGION_NOT_FOUND') rethrow;
}

Key APIs