alfa_vector_mbtiles #

Offline Mapbox Vector Tiles for flutter_map — straight from a local .mbtiles file, no network required.

alfa_vector_mbtiles is a tiny, dependency-light VectorTileProvider that reads gzipped Mapbox Vector Tiles (MVT/PBF) out of a standard .mbtiles SQLite database and feeds them to vector_map_tiles + flutter_map. The result is a fully rendered, pannable, zoomable vector basemap that works 100% offline — ideal for aviation, maritime, field-work, or any app that has to keep a map alive without connectivity.

It powers the offline charts in the Alfaero flight apps.

Screenshots #

⚠️ The images below are placeholders. Drop your real captures over the files in doc/screenshots/ (keep the same filenames) and they will appear here and on the pub.flutter-io.cn gallery automatically.

Day basemap	Night basemap	Offline
Light vector theme	Dark vector theme	Tiles read from local .mbtiles

Why vector .mbtiles? #

You ship one .mbtiles file and render it with as many MapLibre/Mapbox styles as you like.

Features #

• 🛰️ Offline-first — every tile comes from the local SQLite file; zero HTTP requests.
• 🧩 Drop-in for vector_map_tiles — implements VectorTileProvider, so it composes with MemoryCacheVectorTileProvider, VectorTileLayer, TileProviders, and the whole flutter_map stack.
• 🗜️ Handles the MBTiles spec for you — gunzips tile_data and applies the TMS row flip (tile_row = 2^z − y − 1) so tiles land in the right place.
• 📦 Asset bootstrap — copies the bundled .mbtiles asset into the app's databases directory on first run, then memoizes the open Database handle for fast subsequent reads.
• 🎯 Bounds-checked — out-of-range tile requests throw a typed ProviderException instead of returning garbage, and the renderer transparently falls back to lower zoom levels past maximumZoom.
• 🪶 Lightweight — pure Dart on top of sqflite; no native plugin to register.

Supported platforms #

Installation #

flutter pub add alfa_vector_mbtiles

This also pulls the peers you'll use in the layer: flutter_map, vector_map_tiles, and latlong2.

Add your .mbtiles as an asset in pubspec.yaml:

flutter:
  assets:
    - assets/basemap.mbtiles

Quick start #

// `Theme` is hidden from material because `vector_tile_renderer` exports the
// map render `Theme` we use below.
import 'package:flutter/material.dart' hide Theme;
import 'package:flutter_map/flutter_map.dart';
import 'package:latlong2/latlong.dart';
import 'package:vector_map_tiles/vector_map_tiles.dart';
import 'package:vector_tile_renderer/vector_tile_renderer.dart';
import 'package:alfa_vector_mbtiles/alfa_vector_mbtiles.dart';

class OfflineMap extends StatelessWidget {
  const OfflineMap({super.key, required this.theme});

  /// A `vector_tile_renderer` Theme built from a MapLibre/Mapbox style JSON.
  final Theme theme;

  @override
  Widget build(BuildContext context) {
    return FlutterMap(
      // flutter_map v4 API (the version this package depends on):
      // use `center`/`zoom` (v6+ renamed these to `initialCenter`/`initialZoom`).
      options: MapOptions(
        center: LatLng(-23.5505, -46.6333), // São Paulo
        zoom: 12,
        maxZoom: 18,
      ),
      children: [
        VectorTileLayer(
          theme: theme,
          tileProviders: TileProviders({
            // The source name MUST match the `source` used by your style JSON
            // (e.g. 'openmaptiles').
            'openmaptiles': MemoryCacheVectorTileProvider(
              delegate: AlfaVectorMBTilesProvider(
                mbtilesPath: 'assets/basemap.mbtiles',
                // Max zoom *stored in the file* — not the map's max zoom.
                // The renderer over-zooms past this automatically.
                maximumZoom: 14,
              ),
              maxSizeBytes: 2 * 1024 * 1024, // 2 MB in-memory tile cache
            ),
          }),
        ),
      ],
    );
  }
}

A complete, runnable app (with a bundled sample .mbtiles and an OSM-Bright style) lives in example/.

API reference #

AlfaVectorMBTilesProvider #

AlfaVectorMBTilesProvider({
  required String mbtilesPath,
  int maximumZoom = 16,
});

Implements VectorTileProvider from vector_map_tiles, so it can be wrapped by MemoryCacheVectorTileProvider and handed to VectorTileLayer / TileProviders.

ProviderException #

Thrown for invalid/out-of-range tile coordinates.

class ProviderException implements Exception {
  final Retryable retryable; // Retryable.retry | Retryable.none
  final String message;
  final int? statusCode;
}

How it works #

flutter_map (VectorTileLayer)
   │  asks for tile z/x/y
   ▼
MemoryCacheVectorTileProvider        ← in-memory LRU cache (optional but recommended)
   │  cache miss
   ▼
AlfaVectorMBTilesProvider.provide()
   │  validates z/x/y against 2^z bounds
   ▼
MBTilesUtility.getVectorTileBytes()
   │  1. opens the .mbtiles (copied from asset → databases dir on first call)
   │  2. SELECT tile_data WHERE zoom_level=z AND tile_column=x
   │                            AND tile_row = (2^z − y − 1)   ← TMS flip
   │  3. gunzip(tile_data)  →  raw MVT/PBF bytes
   ▼
vector_tile_renderer  →  painted vector tile

The decoded bytes are standard Mapbox Vector Tiles, so any MapLibre/Mapbox GL style that targets your source layers will render correctly.

Generating a compatible .mbtiles #

The file must contain gzipped MVT tiles in the tiles table (the OpenMapTiles / OpenStreetMap schema is the common case). Typical toolchains:

• tilemaker — OSM .pbf → vector .mbtiles locally.
• planetiler — fast OSM → vector .mbtiles.
• tippecanoe — GeoJSON/feature data → vector .mbtiles.
• Extract a region from an existing planet PMTiles/MBTiles set.

Pair it with an OpenMapTiles-compatible style (e.g. OSM Bright, Positron, Dark Matter) converted to a vector_tile_renderer Theme via ThemeReader.

Performance tips #

• Always wrap the provider in MemoryCacheVectorTileProvider — vector tiles are expensive to decode; caching the decoded geometry avoids re-reading SQLite on every frame.
• Keep maximumZoom honest: a too-high value makes the renderer ask for tiles that don't exist; a too-low value triggers heavy over-zoom rendering.
• Ship a region-trimmed .mbtiles, not the planet — startup copies the asset to disk once.
• For very large files, consider lazy-copying or streaming the asset instead of bundling it.

Troubleshooting #

Roadmap #

• ❌ Optional XYZ (non-flipped) tile order support.
• ❌ Pluggable asset → disk copy strategy (stream large files).
• ❌ Desktop/FFI first-class support out of the box.
• ❌ flutter_map v6+ / vector_map_tiles latest compatibility track.

Contributions welcome — see issues.

Credits #

This package builds on the original vector_mbtiles approach for reading vector tiles from MBTiles in flutter_map, repackaged and maintained as alfa_vector_mbtiles for the Alfaero apps. Thanks to the upstream authors and the flutter_map / vector_map_tiles communities.

License #

MIT © Levi Costa.

Map data and styles you render are subject to their own licenses (e.g. OpenStreetMap / OpenMapTiles require attribution — keep it visible).