Skip to content

v3.0.0-rc.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@O-Hannonen O-Hannonen released this 22 Sep 14:36
· 46 commits to main since this release
v3.0.0-rc.1
d36dabf

Important

For full migration guide, check MIGRATION.md

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
Assets 2
Loading