v0.27.0

[gabbopalma]

Release 0.27.0

The plugin has a documentation site now, at maplibre.org/flutter-maplibre-gl: a guide for every part of the API, each with a live map you can pan and click.

This release regenerates the whole style property surface from the current MapLibre style spec, closes long-standing gaps between the three platforms, and cuts start-up time and the cost of large data updates. Upgrading costs little: the only compile-time change is SourceProperties.copyWith moving to named parameters, plus one small change for Android apps and one or two for web apps, all below.

Actions needed

• Android: a map now survives its activity being destroyed and recreated, but your style content does not come back with it. Add sources, layers and images inside onStyleLoadedCallback, which fires again after every recreation, rather than in onMapCreated or initState. See the migration guide (Android: Survive "Don't keep activities" and config changes #805).
• Web: the plugin now loads MapLibre GL JS itself. Delete the maplibre-gl.js script tag and the maplibre-gl.css link tag from web/index.html: if they stay, your pinned copy silently overrides the version the plugin is tested against. See the migration guide ([FEATURE] Load maplibre-gl-js from the plugin instead of from every app's index.html #928).
• Web: MapLibre GL JS 6 requires WebGL2 and no longer falls back to WebGL1, so a browser without it (Safari and iOS before 15) shows no map. Point MapLibreMap.webLibrarySource at a version 5 build to keep those browsers working. Version 6 also slices vector tiles instead of overscaling them, so queryRenderedFeatures can return a different set of features. See the migration guide (feat(web): move the engine to MapLibre GL JS 6 #943).
• SourceProperties.copyWith takes named parameters instead of a dozen required positional ones, so props.copyWith(cluster: true) works and future spec additions stop breaking every caller. Calls that passed values positionally need the parameter names added (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957).
• Expressions.xor never meant xor: ^ is the style spec's exponentiation operator, so the expression raised the first input to the power of the second. It is now Expressions.power, and Expressions.modulo replaces the misspelled Expressions.precent. The old names still work as deprecated aliases, so nothing stops compiling, but any style built with xor was doing something else (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957).
• Android, iOS: the two offline download errors that carried a vendor name are renamed, mapboxTileCountLimitExceeded to tileCountLimitExceeded and mapboxInvalidRegionDefinition to invalidRegionDefinition. When they fire does not change, but a catch matching either old PlatformException code needs the new one (Release 0.27.0 #956).

Added

• Android, iOS, Web: addColorReliefLayer() colours the terrain by elevation from a raster DEM source, the hypsometric tint of a physical map. The colour ramp is a colorReliefColor expression over Expressions.elevation, and colorReliefOpacity sets how strongly it covers what is below. See the color relief guide (Add the color-relief layer #958).
• Android, iOS, Web: addBackgroundLayer() paints the whole map with backgroundColor or tiles it with backgroundPattern, the one layer type with no source. Pass belowLayerId to place it under the layers it backs. Most published styles already carry a layer called background, so reusing that id fails with layerAlreadyExists. Changing its properties after adding it can stop it drawing while the style's own background layer is still there (maplibre-native#4502). See the background layer guide (Add the background layer #959).
• Web: setProjection() switches between the mercator, globe and vertical-perspective projections, or interpolates between them by zoom. setTerrain() raises the map by the elevation of a raster DEM source, with null to flatten it again, and setSky() draws the sky and the atmosphere above the horizon. All three throw an UnsupportedError on Android and iOS, where MapLibre Native implements none of them yet. See the globe, terrain and sky guide (Expose the style root objects: sky, terrain, projection, light and global state #960).
• Android, iOS, Web: the style property surface is regenerated from the current MapLibre style spec instead of a four-year-old copy. New layer properties: textVariableAnchorOffset on symbols, hillshadeMethod and hillshadeIlluminationAltitude for multidirectional hillshading. New expressions: Expressions.distance, within, indexOf, slice and elevation (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957).
• MapLibreMap.preWarm() starts the map engine during app start-up, for apps whose first screen is a map. Saves roughly 170 to 480 ms on Android, 45 to 165 ms on iOS and 10 to 50 ms on web (feat: add preWarm() API for Android, iOS, and Web #867).
• Android: feature state (setFeatureState, getFeatureState, removeFeatureState) works on Android as well as web, so single features can be restyled without re-feeding the source. iOS throws; its SDK does not expose the API yet. promoteId stays web-only, so Android features need a top-level id in the GeoJSON. See the feature state guide ([FEATURE] Support feature-state (setFeatureState / removeFeatureState) on Android & iOS #889).
• Android, iOS: offline regions can move between devices. exportOfflineDatabase() writes a shareable copy, mergeOfflineRegions() imports one (now on iOS too), and getOfflineDatabasePath() locates the store. See the offline regions guide ([BUG] mergeOfflineRegions not implemented on iOS (MissingPluginException) #886).
• Android, iOS, Web: the location puck can be driven from your own position updates instead of the device GPS, with no location permission needed: locationSource: ManualLocationSource() plus controller.updateManualLocation(). See the user location guide ([FEATURE] Support app-provided/manual location source for user location display #840).
• Android, iOS, Web: getClusterExpansionZoom() gives the zoom at which a cluster splits, so a cluster tap can zoom to exactly that instead of guessing with zoom + 2. getClusterLeaves() and getClusterChildren() read the points behind a cluster. All three take the cluster feature's cluster_id. See the cluster guide ([FEATURE] Expose getClusterExpansionZoom (and cluster leaves/children) in the Flutter wrapper #896).
• getLayerProperties() and getSourceProperties() read a layer's or source's properties by id, in the same shape on every platform, or null if the id is unknown. On iOS only what came with the style is readable, so a layer or source you added at runtime answers null there while Android and web answer normally ([FEATURE] Get SourceProperties and LayerProperties objects by id #513, iOS: getLayerProperties/getSourceProperties return null for runtime-added layers and sources #985).
• Android, iOS, Web: setLight() sets the style's light source, which shades extruded geometries: anchor, position, color and intensity. Android and iOS take constant values, web also accepts expressions; Android answers INVALID_ARGUMENT for a value it cannot take. See the globe, terrain and sky guide (Expose the style root objects: sky, terrain, projection, light and global state #960).
• setPadding() keeps map content centred while a bottom sheet or side panel covers part of the map, instead of passing padding to every camera call (Add support for 'setPadding' #258).
• pauseMap() and resumeMap() stop and restart rendering for a map that is alive but off screen, such as one on an inactive tab. No-op on web (Android: Survive "Don't keep activities" and config changes #805).
• Android, iOS: setTrackingCameraOptions() pitches the camera without giving up the active tracking mode, for a navigation-style view that stays tilted while it keeps following the user. On web it throws an UnsupportedError. See the user location guide ([FEATURE] Expose native tiltWhileTracking for location tracking modes #888).
• Web: setGlobalStateProperty() sets a value in the style's global state, which the Expressions.globalState expression reads, so one switch restyles any number of layers at once. Android and iOS throw an UnsupportedError. See the expressions guide (Expose the style root objects: sky, terrain, projection, light and global state #960).
• Web: MapLibreMap.webLibrarySource chooses where MapLibre GL JS comes from: the build the plugin is tested against, a self-hosted copy, or one the page loads itself. MapLibreMap.ensureWebLibraryLoaded() completes once MapLibre GL JS is loaded, for calling into it directly, for example addProtocol ([FEATURE] Load maplibre-gl-js from the plugin instead of from every app's index.html #928).
• Android, iOS, Web: fillExtrusionRoundedCornerDistance rounds the corners of extruded shapes. Its generated dartdoc still reads not on js, because the pinned style spec records MapLibre GL JS support for it as an open issue; it shipped in GL JS 6.2.0 and works on web (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957).
• Android, iOS, Web: clusterMinPoints on a GeoJSON source sets how many points have to fall together before they become a cluster, instead of the fixed default of two (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957, Forward the new source options to the native SDKs, and reject the one they cannot decode #981).
• Android, iOS: attributionButtonColor tints the attribution button, for styles where the default tint is hard to see. No effect on web (Android: Survive "Don't keep activities" and config changes #805).
• iOS: LocationEnginePlatforms.iOS takes intervalMs and pulseWindowMs to pulse GPS instead of tracking continuously, easing battery use on maps that stay open a long time. The default keeps continuous tracking (feat(ios): add intervalMs to LocationEnginePlatforms.iOS for GPS pulsing #901).
• Android: volatile on vector, raster and raster-dem sources keeps their tiles out of the on-disk cache, for tiles that change often or must not be stored. The iOS SDK exposes no equivalent and MapLibre GL JS will not implement one, so it has no effect there (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957, Forward the new source options to the native SDKs, and reject the one they cannot decode #981).
• Web: properties MapLibre GL JS supports but MapLibre Native does not implement yet are exposed too: iconOverlap and textOverlap on symbols, fillLayerOpacity and lineLayerOpacity, resampling on raster and hillshade layers, filter on GeoJSON sources, the custom raster-dem encoding with its factors, and the Expressions.globalState, join and split expressions. Android and iOS ignore them, except the custom encoding, which now throws, and join and split, which work on Android since 13.5.0 (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957, Forward the new source options to the native SDKs, and reject the one they cannot decode #981).

Fixed

• Android: a map no longer stays blank for good after its activity is recreated, whether by "Don't keep activities", memory pressure or rotation; the camera position comes back with it (Android: Survive "Don't keep activities" and config changes #805).
• Android: icons added with addImage are visible again, at the right size on high-density screens. Since 0.26.0 they could be dropped whenever draggable annotations were in use, which is the default. Undecodable bytes now report a clear error instead of crashing (fix(android): temporary workaround for icon atlas bug (maplibre-native#4326) #866, fix(android): restore bitmap decode options of addImage #868).
• Android, iOS: symbols added with addSymbol are visible again on styles whose glyph server does not host the old default font; a missing font used to hide the whole symbol, icon included. The default is now Noto Sans Regular; for another font use addSymbolLayer with textFont (fix: default SymbolManager text font to Noto Sans Regular #940).
• Android, iOS: losing the network no longer cancels an offline region download, nor deletes the region with it on iOS. The SDK retries those failures itself once the connection is back; only the tile count limit stops a download now (Offline downloads are cancelled by any network error, and iOS deletes the region too #986).
• Android, iOS: adding or updating a GeoJSON source with a large payload no longer blocks the UI for the whole encode. Large payloads are encoded in the background, cutting the blocking time by a factor of two to three (Performance issue - Main isolate is blocked when encoding geojsonFeature #366).
• Android: a hillshade layer takes its colours again. hillshadeShadowColor and its three companions became arrays in MapLibre Native 6.24 for multidirectional hillshading, so a single value was rejected with Expected array<color> but found string instead and the layer silently kept the default black and white. A single value is now wrapped for you on Android and iOS, and a list is passed through (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957).
• Android, iOS, Web: queryRenderedFeaturesInRect() applies the filter it is given; no platform decoded it, so the answer held every feature in the rectangle. Note that this call takes the filter as a JSON string, unlike queryRenderedFeatures() ([BUG] iOS: queryRenderedFeatures and querySourceFeatures silently drop features that fail to encode #949, fix: honour the filter of queryRenderedFeaturesInRect on Android and web #953).
• A map that fails to be created now reports the failure. Code awaiting the controller, onMapCreated included, used to wait forever for a map that never arrived, with only an unhandled error in the console (feat(web): move the engine to MapLibre GL JS 6 #943).
• Android, iOS: downloading an area that is already downloaded replaces its region instead of adding a duplicate. iOS keeps the region id the app already knows; Android assigns a new one, so read it back from the returned OfflineRegion ([BUG] mergeOfflineRegions not implemented on iOS (MissingPluginException) #886).
• Android, iOS: setLayerProperties() works on fill-extrusion and heatmap layers too; both used to answer UNSUPPORTED_LAYER_TYPE (Expose the style root objects: sky, terrain, projection, light and global state #960).
• Android: maxzoom on a GeoJSON source is applied again. The converter read a camel-cased key the Dart side never sends, so the value was dropped on Android while iOS and web honoured it (Forward the new source options to the native SDKs, and reject the one they cannot decode #981).
• Android: queryRenderedFeatures() and querySourceFeatures() say what is wrong with a call they cannot answer: STYLE_NOT_READY before the style has loaded, INVALID_ARGUMENT for a missing sourceId, layerIds or query geometry. The failure used to arrive as a bare error carrying a NullPointerException message (fix(android): say what is wrong with a feature query that cannot be answered #954).
• Android: merging an offline database whose regions carry no metadata, such as one produced by maplibre-native, no longer fails with type 'Null' is not a subtype of type 'Map<String, dynamic>' ([BUG] mergeOfflineRegions throws type error when metadata is missing #865).
• iOS: queryRenderedFeatures() and querySourceFeatures() no longer skip a feature that failed to serialize without telling you, and no longer hang on a call they cannot answer, such as one made before the style has loaded ([BUG] iOS: queryRenderedFeatures and querySourceFeatures silently drop features that fail to encode #949).
• iOS: queryCameraPosition() returns the camera position even when trackCameraPosition is false, matching Android. It used to return null (feat: standardize queryCameraPosition across platforms (fix iOS, implement web) #892).
• iOS: controller.cameraPosition no longer sticks on a NaN zoom from a camera event that arrived before the first layout, which misplaced camera-anchored content on maps the user had not touched ([BUG] iOS: camera events before first layout carry NaN zoom and poison the controller's cached cameraPosition #903).
• Web: onMapIdle now fires, matching Android and iOS; code waiting on it never ran (Add onMapIdle callback for detecting render completion #857).
• Web: getFeatureState() returns the state instead of throwing, and reports no state as null rather than an empty map. removeFeatureState(sourceId) with no feature id now resets the whole source instead of doing nothing. A stateKey with no featureId is rejected. Both match Android ([FEATURE] Support feature-state (setFeatureState / removeFeatureState) on Android & iOS #889).
• Web: querySourceFeatures() now reports an error when it is called before the style has loaded, matching Android and iOS. It answered with an empty list, which the caller cannot tell apart from a source holding no features (fix(web): report querySourceFeatures called before the style has loaded #952).
• Web: queryCameraPosition() is implemented; it used to throw UnimplementedError (feat: standardize queryCameraPosition across platforms (fix iOS, implement web) #892).
• Web: updateContentInsets and the new setPadding no longer throw UnimplementedError (Add support for 'setPadding' #258).
• The bundled LICENSE no longer breaks Flutter's license collector, which showed an untitled, truncated first entry on every dependent app's showLicensePage() ([BUG] LICENSE file formatting breaks Flutter's license collector, causing a blank entry on the Flutter "Licenses" screen #895).

Changed

• Web: MapLibre GL JS upgraded from 5 to 6.4.1; see Actions needed above. Over 6.2 this fixes a permanent frame-rate drop after a style switch, a rejected missing-image resolver taking the rest of its batch down with it, globe zoom drifting away from the pointer, globe panning stalling at the poles, and an attribute-sanitising hole in popup and marker HTML (feat(web): move the engine to MapLibre GL JS 6 #943).
• Android: MapLibre Native upgraded from 13.3.0 to 13.5.0 (13.4.0, 13.4.1, 13.5.0), plus OkHttp 5.4.0, Play Services Location 21.4.0 and androidx.core-ktx 1.18.0. 13.5.0 repaints symbol paint properties driven by feature state, fixes a surface-changed ANR and works around a device-lost crash on Adreno GPUs (chore(android): bump MapLibre Android SDK 13.3.0 -> 13.3.1 #877, chore(deps): bump androidx.core:core-ktx from 1.17.0 to 1.18.0 #919, chore: bump MapLibre Native (Android 13.4.1, iOS 6.28.0) and drop two unused Android dependencies #929).
• iOS: MapLibre Native upgraded from 6.27.0 to 6.28.0 (release notes): the map view is no longer blurry in landscape on iPad (chore: bump MapLibre Native (Android 13.4.1, iOS 6.28.0) and drop two unused Android dependencies #929).
• iOS: the plugin supports Flutter's Swift Package Manager integration. The CocoaPods podspec still ships, so CocoaPods apps need no migration (feat(ios): build via Swift Package Manager #891).
• Android, iOS: a raster-dem source with encoding: "custom" now throws an UnsupportedError from addSource(). MapLibre Native decodes only the mapbox and terrarium formulas and used to read custom tiles as mapbox-encoded, drawing a plausible map from wrong elevations. Only addSource() is checked: the same encoding declared inside MapLibreMap.styleString is still decoded as mapbox without an error. Custom encoding keeps working on web (Forward the new source options to the native SDKs, and reject the one they cannot decode #981).
• Android, iOS: panning a pitched map no longer moves the camera past the horizon, and changing a layer's source-layer or source-id now takes effect (chore: bump MapLibre Native (Android 13.4.1, iOS 6.28.0) and drop two unused Android dependencies #929).
• The style spec the code is generated from is now a verbatim copy of a pinned upstream release (@maplibre/maplibre-gl-style-spec, currently 26.2.1). A weekly workflow reports what a newer release would bring to each platform and opens the update PR, and properties the native SDKs do not implement yet are generated for web only, so upgrading the SDKs unlocks them automatically (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957).
• Every generated layer property, source option and expression now documents which platforms implement it, from the spec's own sdk-support metadata: iconOverlap reads basic functionality with js (not on android, ios) instead of claiming all three. Where the spec credits a platform whose SDK exposes no such API, the docs say so rather than repeat the spec (Regenerate from pinned MapLibre style spec 26.2.1, with per-platform gating and a repeatable drift check #957, Forward the new source options to the native SDKs, and reject the one they cannot decode #981).
• The error from addSymbol, addCircle, addLine and addFill when the annotation manager is missing now names the type and both causes: the style has not finished loading, or that type is not in the widget's annotationOrder ([BUG] AnnotationMnager not initialised when adding symbols simply #910).
• Android: the Kotlin Gradle Plugin is applied only below AGP 9, so builds on AGP 9 or later no longer break. Nothing changes on AGP 8 (Migrate Android plugin to Flutter Built-in Kotlin for AGP 9 #905).
• Android: the unused android-plugin-annotation-v9 and android-plugin-offline-v9 dependencies are dropped, so apps pull two fewer artifacts (chore: bump MapLibre Native (Android 13.4.1, iOS 6.28.0) and drop two unused Android dependencies #929).
• Android: the plugin builds against NDK 28.2.13676358, matching Flutter's default (Release 0.27.0 #956).

Docs

• New guides for user location, startup and performance and feature state ([FEATURE] Support app-provided/manual location source for user location display #840, feat: add preWarm() API for Android, iOS, and Web #867, [FEATURE] Support feature-state (setFeatureState / removeFeatureState) on Android & iOS #889).
• Annotations: the two conditions every annotation depends on, and the constraints of both APIs, are now stated in one place ([BUG] AnnotationMnager not initialised when adding symbols simply #910).
• Android: MapLibreMap.useHybridComposition was documented with the wrong default; it has been false since 0.16.0. Its docs and the performance page now say what each value selects (Fixing hybrid composition by enabling textureMode when necessary #816).
• Example app: new Manual Location Source and Feature State pages, and the Offline Regions demo now walks through the export and import round-trip ([FEATURE] Support app-provided/manual location source for user location display #840, [BUG] mergeOfflineRegions not implemented on iOS (MissingPluginException) #886, [FEATURE] Support feature-state (setFeatureState / removeFeatureState) on Android & iOS #889).
• Example app: the Data-Driven Expressions demo drew the USA as a triangle across the Atlantic, because one coordinate was missing its minus sign. Its polygon is now a bounding box over the contiguous states (Release 0.27.0 #956).

Contributors

• @m-schmale made their first contribution in Android: Survive "Don't keep activities" and config changes; add pauseMap/resumeMap API #824
• @RyanHolanda made their first contribution in feat: add preWarm() API for Android, iOS, and Web #867
• @Nico04 made their first contribution in Offline regions: mergeOfflineRegions on iOS, export APIs, download de-duplication #887
• @AlexRepaire made their first contribution in feat(ios): add intervalMs to LocationEnginePlatforms.iOS for GPS pulsing #901
• @JulianBissekkou
• @gabbopalma

Full Changelog: v0.26.2...v0.27.0

---

This discussion was created from the release v0.27.0.