Skip to content

v3.0.0

Latest
Latest

Choose a tag to compare

View all tags
@maios maios released this 02 Oct 11:05
· 46 commits to main since this release
v3.0.0
cc0fca4

🌐 Mapbox Maps Flutter now supports web

Mapbox Maps Flutter on web

This version adds first-class web support powered by Mapbox GL JS. Most existing MapWidget and MapboxMap code now runs on Android, iOS, and web from one Flutter codebase.

  • Same package and import. Continue depending only on mapbox_maps_flutter and importing package:mapbox_maps_flutter/mapbox_maps_flutter.dart. The platform implementations are included automatically.
  • Three platforms, one API. Core camera, gesture, viewport, location, style, source, layer, featureset, and Interaction APIs are available across Android, iOS, and web.
  • No manual GL JS setup. The plugin loads its pinned GL JS version automatically—no <script> or stylesheet tags are required.
  • Browser-native input. Web supports keyboard navigation, mouse-wheel zoom, box zoom, and correct input blocking by Flutter widgets.
  • Web parity is still growing. Annotation managers and some APIs are not yet available on web. Unsupported methods fail explicitly at runtime.

For dependency and platform setup, see the installation guide.

Important

Upgrading from v2? See the v3 migration guide for API replacements, before-and-after examples, and the complete migration checklist.

Note

If your app enforces a Content Security Policy, allow scripts and styles from api.mapbox.com so the plugin can load Mapbox GL JS.

What's new ✨

Web support

  • Web platform support. Most existing v2 code now runs on web. See Platform API coverage for current availability.
  • Keyboard gestures. gestures.keyboard.gestureEvents reports keyboard-driven camera changes from arrow keys, +, -, and Shift+arrow combinations. Keyboard input respects scrollEnabled, rotateEnabled, and pitchEnabled.
  • Web-specific gesture settings. GesturesSettings.scrollZoomEnabled, boxZoomEnabled, and pitchWithRotateEnabled control wheel or trackpad zoom, box zoom, and Ctrl+drag pitch. These settings have no effect on Android or iOS.
  • Dynamic GeoJSON sources. GeoJsonSource.dynamicData maps to the style specification's dynamic option and is required on web when using addGeoJSONSourceFeatures, updateGeoJSONSourceFeatures, or removeGeoJSONSourceFeatures. It has no effect on Android or iOS.

A more ergonomic Flutter API

v3 streamlines the public API around more consistent, typed, and Dart-native patterns:

  • MapWidget is now a StatelessWidget, with camera state represented by viewport states and animated through ViewportController.
  • The Interaction API replaces map tap and long-tap widget callbacks.
  • Pan, zoom, rotate, and pitch expose typed gesture event streams.
  • Style APIs are available directly on MapboxMap and Snapshotter; the .style sub-object is deprecated.
  • Strongly typed values such as StyleImage and sealed RenderedQueryGeometry reduce reliance on loosely structured data.

These changes make common workflows easier to discover and compose while providing a consistent API across Android, iOS, and web.

Additional APIs

  • Indoor API (experimental). MapboxMap.indoor exposes indoor floor updates through indoorUpdates and lets you switch floors with selectFloor(floorId) on Android, iOS, and web.

  • Typed style images. StyleImage is the new input and output type for addImage, updateImageForSource, and getImage. Use .bytes for PNG, JPEG, or WebP data and .rgba for premultiplied pixels. The MbxImage-based APIs are deprecated.

  • Remove style terrain. removeStyleTerrain() removes terrain while keeping its source.

  • Sealed RenderedQueryGeometry. Query geometry is now represented by:

    • ScreenCoordinateRenderedQueryGeometry
    • ScreenBoxRenderedQueryGeometry
    • ScreenCoordinateListRenderedQueryGeometry

    Continue constructing values with fromScreenCoordinate(), fromScreenBox(), or fromList(). Use pattern matching instead of the deprecated value and type accessors.

Bug fixes 🐞

All platforms

  • Indoor selector. MapboxMap.indoorSelector no longer throws on Android and now appears by default on iOS.

Android and iOS

  • Point annotation image updates. PointAnnotationManager.update() now applies a new image even when iconImage named a previous registration (#532). Leave iconImage unset to let the SDK derive the style-image name from the image content, or set it explicitly.

Breaking changes ⚠️

v3 is a major release and includes changes required to support its new API design and federated architecture. Most migrations are straightforward, especially for applications that already replaced deprecated v2 APIs.

Key changes include:

  • MapWidget.cameraOptions was replaced by MapWidget.viewport.
  • setStateWithViewportAnimation was replaced by ViewportController.moveTo.
  • Map tap and long-tap widget listeners were replaced by the Interaction API.
  • Deprecated v2 APIs, including MapWidget.getMapboxMap(), were removed.
  • Style and settings APIs use more consistent method and manager names.

Android rendering changes

  • Hybrid Composition is now the default. The default hosting mode changed from Virtual Display to AndroidPlatformViewHostingMode.HC. Set MapWidget.androidHostingMode to retain another hosting mode.
  • SurfaceView is now the default. Maps render into a SurfaceView instead of a TextureView, avoiding a per-frame copy. Set MapWidget.textureView: true when using a transparent background (isOpaque: false) or the VD or TLHC_VD hosting modes.

iOS

  • Style images return raw RGBA data. getImage and APIs built on it return raw premultiplied RGBA data instead of PNG data, matching Android. Decode the returned data as RGBA.

See the v3 migration guide for the complete list of breaking changes and migration steps.

Platform API coverage

All v2 features remain available on Android and iOS. Most core APIs are also available on web, but some platform-specific functionality is not yet supported.

Not currently supported on web:

  • Annotation managers
  • Offline maps and tile storage
  • Standalone Snapshotter
  • Map recording and replay
  • Custom HTTP headers
  • LongTapInteraction

Some additional APIs have partial web support. Methods unavailable on a platform throw UnimplementedError when support is planned or UnsupportedError when the capability is unavailable by design.

Dependency updates

Assets 2
Loading