A streamlined, more efficient way to build map interactions is now available in Mapbox GL JS for web v.3.8 and Mobile Maps SDKs v.11.8 as experimental APIs. The new APIs allow developers to define interactions with basemap and custom map features with a unified system across platforms. The new system significantly lowers the amount of code required to define interactions while retaining the full power of the existing APIs. 

A unified approach saves time and resources

Before, developers had to manually define map interactions by writing code to listen to and dispatch gesture events, query rendered features from the map, and update feature states accordingly. Now, interactions can easily be accomplished using the new Interactions API.

With the old approach, code defining a simple interaction might have looked something like this:

mapView.gestures.onMapTap.observe {
    [weak self] context in
        let options = RenderedQueryOptions(layerIds: [ /** list layers here */ ], filter: nil)
    mapView.mapboxMap.queryRenderedFeatures(with: context.point, options) {
        switch result {
            case.success(let features):
                // dispatch tapped features to consumers.
                case.failure(let error):
                // handle error.
        }
    }
}.store(in: & cancelables)

With the new API, developers only need to add interactions:

mapboxMap.addInteractions(TapInteraction(.layer("custom-layer")) {
    feature,
    context in
    print("feature: \(feature.id) tapped at: \(context.point)")
    return true
})

The new system also enables mixing annotations (like PointAnnotation) with layers to display data on the map while preserving rendering order for interactions. The top-most feature — whether an annotation or a layer — handles taps first, and if it does, underlying features are ignored. You can also manage taps on the basemap separately.

Implementing this used to require significant effort, including specifying layer identifiers for annotations:

/// old approach
let options = RenderedQueryOptions(layerIds: [
    "custom-layer-1",
    /* list annotations layers here */
], filter: nil)
mapView.mapboxMap.queryRenderedFeatures(with: context.point, options)

The new interactions API allows this out of the box — no code required.

Basemap interactions now available in Mapbox Standard

Prior to this capability, interaction with basemap features was not possible in the Mapbox Standard 3D style. With the introduction of the Featuresets API, it is now possible. You can start experimenting with the new capabilities using the standard-experimental-ime endpoint.

With the new Featuresets, developers can access selected features from the imported styles in Mapbox Standard, which were initially hidden. This allows them to define interaction with the basemap features. Additionally, Featuresets allow developers to define their own features in the base style and import them to other styles - giving flexible control over features across styles.

Example: Enhance the real estate search experience

Use Interactions to highlight selected buildings and icons, effectively drawing focus to the listing and giving your application a more dynamic feel. This can also drive a better understanding of the listing in relation to surroundings—particularly at lower zoom levels. Real estate organizations can serve a pop-up with more listing information when the user clicks. This is helpful for quickly browsing many listings directly on the map.

Example: Make navigating easier and more intuitive

With interactive map features, drivers can click a POI, transit label, or airport to set a destination and then start navigating there. While driving, they can reroute to a new destination by tapping on it — to an EV charging station, for example. Upon arrival, buildings or entrances can be highlighted to identify the final destination further.

Coming Soon: Style interactions in Mapbox Studio

Mapbox Studio will soon include tools to configure map interactions for both basemap and custom map elements in every Mapbox style. Developers will be able to quickly iterate on their interaction design using Studio’s visual tools and preview. Once the design meets their needs, they can export iOS, Android and web code snippets directly from Studio to be used in their application.

Conclusion

See examples above and implementation documentation for iOS to understand the API naming conventions and code syntax needed to build interactive map features. More comprehensive documentation for Android and Web will be released together with Mobile SDKs 11.8.0 and GL JS 3.8.0 in early November. Please reach out to your Mapbox contact or Account Manager with any feedback or questions.