flutter_map_vector_tiles 2.12.0
flutter_map_vector_tiles: ^2.12.0 copied to clipboard
Vector tiles for flutter_map: a clean, self-contained MapLibre-style vector tile layer with isolate-based decoding, raster tile caching and screen-space label collision.
πΊοΈ flutter_map_vector_tiles #
Vector tiles for flutter_map.
Renders MapLibre / Mapbox GL styles (MapTiler, OpenFreeMap, Stadia,
Protomaps, β¦) straight from vector tiles, as a plain flutter_map layer.
flutter_map keeps the camera, the gestures and your other layers; this
package only draws the map.
Any MapLibre style Β· 3D buildings Β· hillshade Β· dark styles
Live demo Β· Documentation Β· pub.dev
β¨ Features #
- π¦ One package. MVT decoding, style engine and renderer in one dependency, with no native code.
- π Smooth. Each tile's geometry is rasterized once into a GPU image
(
Picture.toImageSync), so pan, zoom and rotate only move textures. Tiles decode on a pool of worker isolates, viewport-centre first. - π Crisp labels. Drawn in screen space, in the style's own fonts: upright when the map rotates, sharp at any zoom, never cut at a tile seam.
- π«οΈ No white flashes. New tiles fade in over retained ancestor imagery: zoom-ins render from the parent tiles already decoded, zoom-outs from the children.
- ποΈ 3D buildings, hillshade, heatmaps. Along with fills, lines, patterns, symbols and raster layers, drawn as MapLibre draws them.
- βοΈ Works offline. The style and the tiles you visited are cached on disk, in a size-capped cache with no index files to corrupt. PMTiles and MBTiles archives cover whole regions.
- π Queries and feature state. Ask what is drawn at a tap and highlight features from the style.
- π‘οΈ Hard to break. Unknown layer types and exotic expressions degrade per layer with a warning, and a cancelled tile load is a state, never an exception in your crash reporting.
- π Six platforms. Android, iOS, macOS, Linux, Windows and web.
Built for flutter_map β₯ 8.2 and modern Flutter (Impeller). A clean,
self-contained rewrite of the ideas behind
vector_map_tiles;
how the two compare is below.
π Quick start #
1. Install #
dependencies:
flutter_map: ^8.2.0
flutter_map_vector_tiles: ^2.12.0
2. Load a style & drop in the layer #
import 'package:flutter_map/flutter_map.dart';
import 'package:flutter_map_vector_tiles/flutter_map_vector_tiles.dart' as vt;
import 'package:latlong2/latlong.dart';
// Load the style once. MapTiler shown, any MapLibre style URL works.
final style = await vt.StyleReader(
uri: 'https://api.maptiler.com/maps/streets-v2/style.json?key={key}',
apiKey: myMapTilerKey,
).read();
// Use it like any other flutter_map layer:
FlutterMap(
options: MapOptions(
initialCenter: style.center ?? const LatLng(48.137, 11.575),
initialZoom: style.zoom ?? 12,
maxZoom: 21,
),
children: [
vt.VectorTileLayer(
theme: style.theme,
tileProviders: style.providers,
rasterSources: style.rasterSources,
sprites: style.sprites,
glyphs: style.glyphs, // labels in the style's own fonts
),
// Show what the style's sources ask for; most providers require it.
SimpleAttributionWidget(
source: Text(style.attributions.map((a) => a.text).join(' Β· ')),
),
// ...your markers, polylines, etc.
],
);
style.attributions comes pre-parsed: each entry pairs the flattened
text shown above with spans, whose runs keep the url of the <a>
tag they came from. Build from those when your provider's terms call for
tappable links.
3. Clean up #
@override
void dispose() {
style.dispose(); // releases HTTP clients, sprite images & glyphs
super.dispose();
}
βΆοΈ A runnable app lives in example/:
cd example
flutter run --dart-define=MAPTILER_KEY=yourKey
πΌοΈ What it draws #
![]() Buildings as styles draw them by default β¦ |
![]() β¦ and as 3D buildings, with ExtrusionMode.perspective
|
![]() Heatmap layers |
![]() A tap, queried: the top hit in the pill, the building under it highlighted through feature state |
![]() Labels in the style's own fonts |
![]() Labels stay upright when the map rotates (label modes) |
Map data Β© OpenMapTiles Β© OpenStreetMap contributors, styles by OpenFreeMap.
βοΈ Options #
Everything has a default. The ones you are most likely to touch:
| Option | Default | What it does |
|---|---|---|
glyphs |
none | style.glyphs: labels in the style's own fonts instead of the system font |
labelMode |
LabelMode.screen |
LabelMode.tile bakes labels into the tiles: no per-frame label cost, but they turn with the map |
extrusionMode |
ExtrusionMode.flat |
ExtrusionMode.perspective draws fill-extrusion layers as 3D buildings |
tileOffset |
TileOffset.maplibre |
renders 512 px styles as their authors designed them; TileOffset.none shows one zoom level more detail |
diskCacheMaximumSizeInBytes |
50 MB | disk cache for tiles; 0 turns it off |
diskCacheTtl |
14 days | how long a cached tile skips the network |
showLabels |
true |
false turns off all text and icons |
controller |
none | a VectorTileLayerController, for queries and feature state |
logger |
none | const vt.Logger.console() prints style warnings |
StyleReader(language: 'de') shows labels in one language where the
tiles carry it. All options, cache budgets and the frame budget are in
Configuration.
π Tile sources #
Any MapLibre style.json works. Verified with
MapTiler, OpenFreeMap
(free, no key), Stadia Maps, ArcGIS / Esri,
Protomaps and self-hosted servers (TileServer
GL, Martin, β¦).
- PMTiles:
pmtiles://source URLs in a style work out of the box. - MBTiles: through the companion package
flutter_map_vector_tiles_mbtiles. - Your own: implement
VectorTileProvider, four methods. - Web: works, without a disk cache; the style and tile hosts must send CORS headers.
URL shapes per provider, offline behaviour and the browser differences are in Tile sources, offline and web.
π Compared with vector_map_tiles #
Against vector_map_tiles
9.0.0-beta.13, the newest release that runs flutter_map 8 on stable
Flutter (the
10.0.0 betas need
Flutter's main channel for flutter_gpu, per
their README):
| vector_map_tiles 9.0.0-beta.13 | this package | |
|---|---|---|
| Packages | 3 (vector_map_tiles, vector_tile_renderer, executor_lib), plus idb_shim for its web cache |
1 |
| Labels | raster mode (default): baked into each tile image, collision within the tile; vector mode: redrawn with the tiles every frame | a screen-space pass with one global collision pass and upright text (default), or baked into the tile images with LabelMode.tile |
| Style zoom | evaluated at the flutter_map zoom, one level deeper than MapLibre, so label layers open a level early | TileOffset.maplibre by default, as MapLibre renders the style |
| Tile images | 512 px, Picture.toImage, then PNG-encoded into its disk cache before the tile is shown; a revisit decodes the PNG |
256 px Γ device pixel ratio, Picture.toImageSync, kept as GPU textures in an LRU |
Measured with compare/ on a Nothing Phone (1) (Android,
60 Hz), an iPhone 15 Pro Max (iOS, 120 Hz), a MacBook Pro with an M4 Pro
(macOS, 120 Hz) and Chrome on that Mac: same style, same recorded tiles,
a fresh process per run, three runs each (four on the iPhone). "Frames"
is the share of display refreshes that got a frame while the camera
zoomed, panned, rotated or flung. Each cell reads this package /
vector_map_tiles.
| this package / vector_map_tiles | Android | iOS | macOS | Chrome |
|---|---|---|---|---|
Labels baked into the tiles (LabelMode.tile / raster mode): frames |
94β98% / 75β98% | 99.6β100% / 97β100% | 98β100% / 99β100% | 95.5β99.9% / 41β100% |
| β¦ worst frame gap | 50β117 / 67β251 ms | 8β18 / 8β38 ms | 8β25 / 8β42 ms | 13β117 / 11β158 ms |
| Labels drawn every frame (default / vector mode): frames | 91β96% / 20β40% | 99.5β100% / 67β99.8% | 97β100% / 64β99.9% | 95β100% / 3β76% |
| β¦ worst frame gap | 50β100 / 100β1304 ms | 8β17 / 17β133 ms | 8β33 / 14β183 ms | 10β42 / 100β833 ms |
| First complete map (baked / raster) | 0.68 / 2.75 s | 0.35 / 1.74 s | 0.28 / 0.93 s | 1.12 / 2.49 s |
| Downloaded per run (default / raster) | 27.3 / 53.1 MB | 27.3 / 53.2 MB | 27.2 / 51.3 MB | 29.9 / 32.6 MBΒΉ |
ΒΉ In the browser the HTTP cache answers a repeated request, so this
counts each URL once; on macOS, with a smaller window and no HTTP
cache, vector_map_tiles fetched some tiles again.
- All from one build: 2.11.0 with 3D buildings and an experiment in drawing curved street names that was taken out again before 2.11.1, so the frames with labels drawn every frame are not yet measured on the code as it ships.
- 3D buildings (
ExtrusionMode.perspective, labels drawn every frame): 84β92% of frames on Android, 3 to 9 points under the default, 89β100% in Chrome, and 98β100% on iOS and macOS, where they cost nothing measurable. See 3D buildings. - Memory: with baked labels a little less than
vector_map_tiles(264 against 313 MB of GPU memory at the peak on the Android phone); the default needs more GPU memory than baked labels but far less RSS than vector mode (393 against 892 MB). All numbers: Memory. - Label density: at the same camera
vector_map_tilesdraws more labels, because it evaluates the style one zoom level deeper than MapLibre.tileOffset: TileOffset.nonemakes this package do the same. - Not covered yet: the
10.0.0betas.
compare/SUMMARY.md explains the results in plain words; the full tables, and screenshots next to MapLibre GL JS, are in compare/RESULTS.md. To check the numbers on your own devices, follow Reproducing the results: every session's raw data is in the repository, and the scripts measure each one again. With no setup at all, the web demo runs a short version of the benchmark in your browser.
π Documentation #
| Page | What is in it |
|---|---|
| Configuration | every layer and StyleReader option, TileOffset, cache budgets, frame budget and profiling |
| Tile sources, offline and web | tested providers, PMTiles, MBTiles, your own provider, the disk cache, browser differences |
| Style support | layer types, expressions, icons, heatmaps, 3D buildings, global state, and where the result differs from MapLibre |
| Labels | placement and collision, fonts, LabelMode.screen or .tile, label language |
| Querying | what is drawn at a point, feature state |
| Troubleshooting | blank maps, exceptions, labels, web and iOS specifics |
| Architecture | how it works inside, for contributors |
π€ Contributing #
Issues and PRs are welcome! Please run dart analyze && flutter test
before submitting; the suite covers the MVT decoder, expression engine,
caches, grid math and tile store. Run flutter test --platform chrome too
when touching anything platform-sensitive (requires Chrome). CI runs
formatting, analysis and both test suites on every PR.
π€ Built with Claude #
This package is developed with
Claude Code, Anthropic's AI coding agent.
Claude writes much of the code, tests and documentation, and most commits
in the history carry a Co-Authored-By: Claude trailer. The maintainer
directs the work and cuts every release. The instructions Claude works
under (architecture notes, testing and release rules) are checked in as
CLAUDE.md
and
AGENTS.md
files, which are left out of the published package.
π License #
BSD 3-Clause Β© 2026 Jonas Grunau






