mapbox_maps_flutter

What's new ✨

All platforms

• Split the plugin into federated packages: mapbox_maps_flutter (public facade), mapbox_maps_flutter_platform_interface, mapbox_maps_flutter_mobile, and mapbox_maps_flutter_web. Add mapbox_maps_flutter as the app-facing dependency; mobile and web packages are endorsed automatically.
• Introduce StyleImage (.bytes for PNG/JPEG/WebP, .rgba for premultiplied pixels) and prefer it via addImage, updateImageForSource, and getImage. Deprecate the MbxImage-based addStyleImage, updateStyleImageSourceImage, and getStyleImage wrappers. Style image add/has/remove is implemented on web; getImage and image-source updates remain mobile-only for now.
• RenderedQueryGeometry is now a sealed class hierarchy (ScreenCoordinateRenderedQueryGeometry, ScreenBoxRenderedQueryGeometry, ScreenCoordinateListRenderedQueryGeometry) instead of an untyped {value, type} pair. Construct it the same way as before, via fromScreenCoordinate()/fromScreenBox()/fromList(). Use pattern matching on the subclasses to inspect it instead of the now-deprecated, read-only value/type accessors.

Web

• Web is now supported. MapWidget, MapboxMap, gestures, camera, the viewport API (Camera, FollowPuck, Idle, Overview, StyleDefault states, with Default/Easing/Fly transitions), and the location puck all work. The Interaction API is supported except for LongTapInteraction. Annotation managers (Circle, Point, Polyline, Polygon) are not yet implemented.
• Add ornament settings support: compass, scaleBar, logo and attribution are backed by the Mapbox GL JS controls and support partial updates, matching Android and iOS. Some fields have no GL JS counterpart and are stored and returned by getSettings without being applied; see each field's documentation. Note LogoSettings.enabled and AttributionSettings.enabled are a restricted API.
• Add MapboxMap.snapshot() support. It captures the map's current canvas as PNG-encoded bytes, matching Android and iOS.
• Add loadStyleJson support.
• Add gestures.keyboard.gestureEvents, delivering keyboard-driven camera changes (arrow keys, +/-, shift+arrows), and make keyboard input follow the same gesture settings as pointer/touch input: GesturesSettings.scrollEnabled gates arrow-key pan, and .rotateEnabled/.pitchEnabled independently gate Shift+arrow rotate and pitch.
• Add GesturesSettings.scrollZoomEnabled, .boxZoomEnabled, and .pitchWithRotateEnabled to control mouse-wheel/trackpad zoom, box zoom, and whether ctrl+drag combines rotate with pitch (web only; no effect on Android/iOS).
• GesturesSettings.quickZoomEnabled controls tap-and-drag zoom.
• Flutter widgets stacked over the map block clicks/taps, scroll-zoom, and cursor styling from reaching Mapbox GL JS underneath, matching how a widget stacked over a native view would behave.
• MapWidget.styleUri loads the requested style directly, without first loading a default style.
• Document how web keeps a GeoJSON feature id. GL JS keeps the id only if it is a number, or a string that holds a number. It removes all other string ids, and the feature then has no id on web. Use a number for these ids, or put the id in a feature property.
• Add GeoJsonSource.dynamicData, mapping to the dynamic option in the style specification. Set it to true for the source to accept addGeoJSONSourceFeatures, updateGeoJSONSourceFeatures, and removeGeoJSONSourceFeatures. No-op on Android and iOS, which accept feature updates on all GeoJSON sources regardless.
• Decode rgb, hsl, and hsla style-color expressions correctly. rgba expressions were already decoded correctly. gl-native (Android/iOS) folds these into rgba before Flutter reads them back, so mobile is not affected either way.

Android

• Change the default platform-view hosting mode to Hybrid Composition (AndroidPlatformViewHostingMode.HC); it was previously Virtual Display. Set MapWidget.androidHostingMode explicitly to keep the old behaviour.
• Render the map into a SurfaceView by default instead of a TextureView, avoiding the per-frame copy a TextureView requires. Set MapWidget.textureView to true for a transparent background (isOpaque: false) and for the VD and TLHC_VD hosting modes, which cannot display a SurfaceView.

Bug fixes 🐞

iOS & Android

• Fix PointAnnotationManager.update() not applying a new image when the annotation's iconImage still named a previous registration (#532). If you leave iconImage unset, the SDK derives one from a hash of image, so a content change now applies automatically. Set iconImage yourself for full control of the style-image name: for example, to reuse one name across annotations, or to point at a style image added elsewhere without uploading image.

iOS

• getStyleImage (and the deprecated getStyleImage/getImage wrappers built on it) now return raw premultiplied RGBA pixel data instead of a PNG-encoded image, matching Android's existing behavior. Code that decoded the returned data as PNG must decode it as raw RGBA instead.

Breaking changes ⚠️

All platforms

• Remove APIs deprecated in v2: MapWidget.cameraOptions (use viewport), MapWidget.getMapboxMap() (use onMapCreated), MapboxMap.setCustomHeaders and MapboxHttpService.setCustomHeaders (use setCustomHeadersForHost), PointAnnotation.iconImageCrossFade / PointAnnotationOptions.iconImageCrossFade (use PointAnnotationManager.iconImageCrossFade), and the OnMapTapListener / OnMapLongTapListener typedefs (use the Interaction API).
• tileCover and Snapshotter.tileCover are marked experimental and now return OverscaledTileID instead of CanonicalTileID, matching the native SDKs. OverscaledTileID keeps the canonical tile coordinate in its canonical field, and adds overscaledZ and wrap so callers can distinguish overscaled tiles from their canonical zoom level, and tiles that repeat across the antimeridian.

Platform API coverage

Web support is actively being developed. Not all APIs available on iOS and Android are supported on web yet — full parity is coming in future releases. APIs that are not available on a given platform will throw UnimplementedError at runtime.

Dependency Updates

• Update Mapbox Maps SDK to v11.32.0-rc.1
  • For platform-specific updates see: iOS & Android
• Update Mapbox GL JS to v3.31.0
  • See changelog

What's new ✨

• Add GeoJsonSource.dynamicData that maps to the dynamic option in the style specification. On web, set it to true for the source to accept addGeoJSONSourceFeatures, updateGeoJSONSourceFeatures, and removeGeoJSONSourceFeatures. Android and iOS ignore dynamicData and accept feature updates on all GeoJSON sources.
• [web] Fix removeGeoJSONSourceFeatures failing to remove a feature that was added with a numeric id.
• [web] Add ornament settings support: compass, scaleBar, logo and attribution are backed by the Mapbox GL JS controls and support partial updates, matching Android and iOS. Some fields have no GL JS counterpart and are stored and returned by getSettings without being applied; see each field's documentation. Note LogoSettings.enabled and AttributionSettings.enabled are a restricted API.
• [web] Fix addStyleImportFromJSON and updateStyleImportWithJSON. They completed before the style held the fragment, so the next call failed with "Style is not done loading". Both now complete after the style holds the fragment, as on Android and iOS.
• [web] Fix MapWidget ignoring styleUri. The map loaded a default style first, fired onStyleLoaded for it, then loaded the requested style, which removed everything onStyleLoaded had added. The map now loads the requested style directly.
• [web] Document how web keeps a GeoJSON feature id. GL JS keeps the id only if it is a number, or a string that holds a number. It removes all other string ids, and the feature then has no id on web. Use a number for these ids, or put the id in a feature property.

Platform API coverage

Web support is actively being developed. Not all APIs available on iOS and Android are supported on web yet — full parity is coming in future releases. APIs that are not available on a given platform will throw UnimplementedError at runtime.

Dependency Updates

• Update Mapbox Maps SDK to v11.31.0
  • For platform-specific updates see: iOS & Android
• Update GL JS to v3.31.0
  • See changelog

What's new ✨

• Remove APIs deprecated in v2. See the migration guide for upgrade instructions.

• [web] Add MapboxMap.snapshot() support.

• [web] Add loadStyleJson support.

• tileCover and Snapshotter.tileCover (experimental) now return OverscaledTileID instead of CanonicalTileID, matching the native SDKs and preserving overscaling and antimeridian distinctions.

• Add experimental RasterLayer.rasterColorScale for more precise visualization of long-tailed raster-array data.

• Promote SymbolLayer.symbolZOffset to stable.

• Introduce the new StyleImage API for style images, replacing MbxImage-based methods.

  • StyleImage.bytes(...) accepts encoded PNG/JPEG/WebP directly
  • StyleImage also supports raw premultiplied RGBA pixels
  • StyleImage.fromImage(...) creates a style image from a dart:ui Image
  • addStyleImage, updateStyleImageSourceImage, and getStyleImage are deprecated in favor of addImage, updateImageForSource, and getImage, built on StyleImage.
  • getStyleImage (and deprecated wrappers around it) now return raw premultiplied RGBA pixel data instead of a PNG-encoded image, matching Android behavior.
  • MbxImage is deprecated and will be removed in a future release.

  // v2 — MbxImage, manual RGBA decode required
  final decoded = img.decodeImage(pngBytes)!;
  await mapboxMap.style.addStyleImage(
    'my-icon',
    1.0,
    MbxImage(
      width: decoded.width,
      height: decoded.height,
      data: decoded.getBytes(order: img.ChannelOrder.rgba),
    ),
  );
  
  // v3 — StyleImage, pass encoded bytes straight through
  await mapboxMap.style.addImage(
    'my-icon',
    1.0,
    StyleImage.bytes(pngBytes),
  );
  
  // v3 — or build one from a dart:ui Image
  await mapboxMap.style.addImage(
    'my-icon',
    1.0,
    await StyleImage.fromImage(uiImage),
  );

Platform API coverage

Web support is actively being developed. Not all APIs available on iOS and Android are supported on web yet — full parity is coming in future releases. APIs that are not available on a given platform will throw UnimplementedError at runtime.

Dependency Updates

• Update Mapbox Maps SDK to v11.30.0
  • For platform-specific updates see: iOS & Android
• Update GL JS to v3.30.0
  • See changelog

What's new ✨

• Add LineLayer.lineBorderGradient and .lineBorderGradientExpression to color a line's border along its length with a gradient driven by line-progress. Requires a GeoJSON source with lineMetrics: true.
• RenderedQueryGeometry is now a sealed class hierarchy (ScreenCoordinateRenderedQueryGeometry, ScreenBoxRenderedQueryGeometry, ScreenCoordinateListRenderedQueryGeometry) instead of an untyped {value, type} pair. Construct it the same way as before, via fromScreenCoordinate()/fromScreenBox()/fromList(). Use pattern matching on the subclasses to inspect it instead of the now-deprecated, read-only value/type accessors.

Bug fixes 🐞

• Fix an uncatchable crash in MapWidget when the platform view is created before layout completes, on iOS (always) and Android's HC hosting mode (the default) (#1141).
• [web] Fix queryRenderedFeatures querying the whole viewport for an empty fromList([]); it now matches no features, in line with mobile.

Platform API coverage

Web support is actively being developed. Not all APIs available on iOS and Android are supported on web yet — full parity is coming in future releases. APIs that are not available on a given platform will throw UnimplementedError at runtime.

Dependency Updates

• Update Mapbox Maps SDK to v11.29.0
  • For platform-specific updates see: iOS & Android
• Update GL JS to v3.29.0
  • See changelog

• [web] Add GesturesSettings.scrollZoomEnabled, .boxZoomEnabled, and .pitchWithRotateEnabled (web only; no effect on Android/iOS). Behavior change: pinchToZoomEnabled no longer also controls mouse-wheel/trackpad zoom on web (use scrollZoomEnabled), and pitchEnabled no longer also controls whether ctrl+drag combines rotate with pitch (use pitchWithRotateEnabled).
• [Android] Render the map into a SurfaceView by default instead of a TextureView, avoiding the per-frame copy a TextureView requires. Set MapWidget.textureView to true for a transparent background (isOpaque: false) and for the VD and TLHC_VD hosting modes, which cannot display a SurfaceView.
• Fix rgb, hsl, and hsla style-color expressions decoding incorrectly: rgb colors rendered nearly fully transparent, and hsl/hsla colors used the wrong saturation/lightness scale and alpha, producing wrong or (in debug builds) crashing results. rgba expressions were not affected.

[!IMPORTANT] On web, Mapbox GL JS is now loaded automatically: the plugin injects the <script>/<link> tags for the GL JS version it pins (v3.27.0) into the page on first map use. Remove the mapbox-gl.js and mapbox-gl.css tags from your app's web/index.html — a mapboxgl global that is already on the page is reused as-is, so a manually pinned copy silently overrides the version the SDK expects.

If your app enforces a Content-Security-Policy, it must allow script and style sources from api.mapbox.com.

• [Android] Change the default platform-view hosting mode to Hybrid Composition (AndroidPlatformViewHostingMode.HC); it was previously Virtual Display. Set MapWidget.androidHostingMode explicitly to keep the old behaviour.
• [web] Fix Flutter widgets stacked over the map on web not blocking clicks/taps, scroll-zoom, and cursor styling from reaching Mapbox GL JS underneath. The map now respects any Flutter widgets painted on top of it.
• Remove the OnMapTapListener / OnMapLongTapListener typedefs, orphaned since the MapboxMap.onMapTapListener / onMapLongTapListener setters they typed were removed in favor of the Interaction API.
• [web] Add gestures.keyboard.gestureEvents, delivering keyboard-driven camera changes (arrow keys, +/-, shift+arrows) that were previously not observable through the gesture event streams.

• Split the plugin into federated packages and add web support: mapbox_maps_flutter (public facade), mapbox_maps_flutter_platform_interface, mapbox_maps_flutter_mobile, and mapbox_maps_flutter_web. Add mapbox_maps_flutter as the app-facing dependency; mobile and web packages are endorsed automatically.

Dependency Updates

• Update Mapbox Maps SDK to v11.31.1
  • For platform-specific updates see: iOS & Android

New Features ✨

• Introduce experimental RasterLayer.rasterColorScale property, resulting in more precise visualization with long-tailed raster-array data source.
• Promote SymbolLayer.symbolZOffset to stable.

Bug fixes 🐞

• Fix PointAnnotation.iconImageCrossFade and PointAnnotationOptions.iconImageCrossFade missing their @Deprecated annotation, so the analyzer and IDEs showed no warning. Both fields are deprecated in favor of PointAnnotationManager.iconImageCrossFade.

Dependency Updates

• Update Mapbox Maps SDK to v11.31.0
  • For platform-specific updates see: iOS & Android

New Features ✨

• Introduce experimental RasterLayer.rasterColorScale property, resulting in more precise visualization with long-tailed raster-array data source.
• Promote SymbolLayer.symbolZOffset to stable.

Bug fixes 🐞

• Fix PointAnnotation.iconImageCrossFade and PointAnnotationOptions.iconImageCrossFade missing their @Deprecated annotation, so the analyzer and IDEs showed no warning. Both fields are deprecated in favor of PointAnnotationManager.iconImageCrossFade.

Dependency Updates

• Update Mapbox Maps SDK to v11.31.0-rc.1
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.30.4
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.30.3
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.30.2
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.30.1
  • For platform-specific updates see: iOS & Android

New Features ✨

• Add LineLayer.lineBorderGradient and LineLayer.lineBorderGradientExpression to color a line's border along its length with a gradient driven by line-progress. Requires a GeoJSON source with lineMetrics: true.
• Mark Snapshotter.tileCover as experimental, matching the experimental status of the underlying native APIs.

Bug fixes 🐞

• Fix an uncatchable crash in MapWidget when the platform view is created before layout completes, on iOS (always) and Android's HC hosting mode (the default) (#1141).

Dependency Updates

• Update Mapbox Maps SDK to v11.30.0
  • For platform-specific updates see: iOS & Android

New Features ✨

• Add LineLayer.lineBorderGradient and LineLayer.lineBorderGradientExpression to color a line's border along its length with a gradient driven by line-progress. Requires a GeoJSON source with lineMetrics: true.
• Mark Snapshotter.tileCover as experimental, matching the experimental status of the underlying native APIs.

Bug fixes 🐞

• Fix an uncatchable crash in MapWidget when the platform view is created before layout completes, on iOS (always) and Android's HC hosting mode (the default) (#1141).

Dependency Updates

• Update Mapbox Maps SDK to v11.30.0-rc.1
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.29.4
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.29.3
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.29.2
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.29.1
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.29.0
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.28.4
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.28.3
  • For platform-specific updates see: iOS & Android

Dependency Updates

• Update Mapbox Maps SDK to v11.28.2
  • For platform-specific updates see: iOS & Android

• Update Maps SDK to v11.28.1

• Add ModelSource API, exposing the 3D model source (a collection of 3D models, each with its own position, orientation, and node/material overrides).
• Add MapWidget.isOpaque option to control whether the map is rendered as opaque or supports a transparent background. Set to false (together with a transparent style) to enable transparency on iOS; Android already supports this via MapWidget.textureView (#415).
• [iOS] Fix updateSettings on CompassSettings, AttributionSettings, LogoSettings, IndoorSelectorSettings, ScaleBarSettings, GesturesSettings, and LocationComponentSettings resetting omitted fields (position, margins, enabled, scrollMode, puck configuration) to defaults instead of preserving them, matching Android's partial-update behaviour.
• [Android] Fix LocationComponentSettings.updateSettings dropping the previously configured 2D or 3D puck's settings when switching between puck types.

Dependency Updates

• Update Mapbox Maps SDK to v11.27.3
  • For platform-specific updates see: iOS & Android

• Update Maps SDK to v11.27.2

• [iOS] Support GesturesSettings.scrollDecelerationEnabled on iOS (#1127).
• [Android] Migrate to built-in Kotlin.
• Add MapboxMap.httpService.setCustomHeadersForHost to attach custom HTTP headers to a single host only, and MapboxMap.httpService.clearCustomHeaders to remove all configured headers. Host-scoped headers are matched against the request's exact URL host (case-insensitive, no subdomain or substring matching).
• Deprecate MapboxMap.setCustomHeaders: headers set this way are attached to every host the map fetches from — including third-party hosts referenced by styles, sources, sprites, glyphs and tiles — which can leak credentials. Use setCustomHeadersForHost instead.

• [iOS] Fix iOS compass ignoring CompassSettings.fadeWhenFacingNorth (and visibility in general) unless enabled was also set. enabled and fadeWhenFacingNorth are now applied independently, matching the Android behaviour (#602).
• [Android] Use flutter.compileSdkVersion to align Android compileSdk with Flutter SDK

Dependency Updates

• Update Mapbox Maps SDK to v11.25.3
  • For platform-specific updates see: iOS & Android

• Deprecate MapboxMap.onTapListener and MapboxMap.onLongTapListener in favor of the MapboxMap.addInterfaction API.
• Add MapboxMap.httpService.setMaxRequestsPerHost to cap the number of concurrent HTTP requests per host issued by the underlying HTTP service. Useful for reducing the chance of hitting per-token rate limits during offline tile region downloads.