Skip to main content

flutter_map_vector_tiles 2.12.0 copy "flutter_map_vector_tiles: ^2.12.0" to clipboard
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 #

pub package CI license: BSD-3-Clause flutter_map

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.

Munich in the OpenFreeMap Liberty style Midtown Manhattan with 3D buildings Zermatt with a hillshade overlay Munich in the dark Fiord style

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 #

Flat building footprints in Midtown Manhattan
Buildings as styles draw them by default …
The same view with 3D buildings
… and as 3D buildings, with ExtrusionMode.perspective
A heatmap of points of interest over Munich
Heatmap layers
St. Joseph in Munich after a tap: the church highlighted in blue, and a pill naming the query's top hit, poi_r7 Β· St. Joseph
A tap, queried: the top hit in the pill, the building under it highlighted through feature state
Plovdiv with Cyrillic and Latin labels
Labels in the style's own fonts
A rotated map with upright labels
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_tiles draws more labels, because it evaluates the style one zoom level deeper than MapLibre. tileOffset: TileOffset.none makes this package do the same.
  • Not covered yet: the 10.0.0 betas.

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

6
likes
160
points
26.3k
downloads
screenshot

Documentation

API reference

Publisher

verified publishersafenow.app

Weekly Downloads

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.

Repository (GitHub)
View/report issues

Topics

#flutter-map #vector-tiles #maplibre #map #pmtiles

License

BSD-3-Clause (license)

Dependencies

characters, flutter, flutter_map, http, intl, latlong2, meta, path_provider

More

Packages that depend on flutter_map_vector_tiles