Skip to main content

User interaction

Additional Developer Resources

Users interacting with the Mapbox map in your application can explore the map by performing standard iOS gestures on the touchscreen.

The Maps SDK’s GestureManager powers what happens with each gesture. You can allow users to move the map using default gestures, enable and disable specific default gestures, or specify completely custom behavior for one or more gestures.

Default map gestures​

By default the following standard iOS gestures will allow the user to explore the map:

  • Pan around: Hold one finger down on the screen and move it in any direction.
  • Adjust pitch: Hold two fingers down on the screen and move them vertically across the screen.
  • Gradually zoom in/out and rotate: Pinch with two fingers to adjust the zoom level and rotate the map. Move fingers apart to zoom in, move fingers closer together to zoom out, and move fingers in a circular motion to rotate the map (adjust the bearing).
  • Zoom in one zoom level: Double tap on the screen with one finger to zoom in towards the tapped location.
  • Zoom out one zoom level: Single tap on the screen with two fingers to zoom out away from the midpoint of the tapped locations.
  • Quick zoom: Double tap and drag up on the screen to zoom out or double tap and drag down to zoom in.

Map content gestures​

Maps SDK has an extensive system for handling Tap and Long Press gestures on annotations, layers, and the map itself. The events can propagate from the top-most to least visible objects.

// Store tokens until you handle events
var tokens = Set<AnyCancelable>()

// Handle taps on 'house-prices' layer.
mapView.gestures.onLayerTap("house-prices") { feature, context in
    print("Tap on house-prices feature \(feature) at \(context.coordinate)")
    return true // stop propagation
}.store(in: &tokens)

// Handle taps on the map that weren't handled by the 'house-prices' layer.
mapView.gestures.onMapTap.observe { context in
    print("Tap at \(context.coordinate)")
}.store(in: &tokens)

// Cancel subscription
tokens.removeAll()
GUIDE
Map Content Gestures User Guide

Learn how to handle Tap and LongPress gestures on annotations, layers, and the map itself.

Enable and disable default gestures​

Adjust or completely disable pan, rotate, pinch, and double tap gesture recognition by configuring GestureOptions on a GestureManager.

Enable or disable default gestures​

You can find a full list of gestures that can be enabled or disabled in the GestureOptions documentation. For example, to prevent users from changing the pitch of the map, set pitchEnabled to false:

mapView.gestures.options.pitchEnabled = false
Note

Disabling map gestures doesn't affect whether you can change the camera position programmatically.

Configure pan behavior​

There are additional configuration options for pan gestures.

Use panMode to configure the directions in which the map is allowed to move during a pan gesture. By default, the map will move both horizontally and vertically.

Use panDecelerationFactor to adjust how quickly pan deceleration animations happen. This value is multiplied with the velocity vector once per millisecond during deceleration animations, and typical values are slightly less than 1.0. A small change to this value can result in a big difference in deceleration behavior. The raw values of the UIScrollView.DecelerationRate constants are good starting points for tuning the deceleration.

Listen for gesture events​

Gesture events may be observed by implementing the GestureManagerDelegate protocol.

Listen for when a gesture has begun using gestureManager(_:didBegin:), when a gesture has ended and whether there will be additional animations after the gesture has completed using gestureManager(_:didEnd:willAnimate:) (without indicating whether gesture-based animations have completed), or when animations triggered due to a gesture have ended using gestureManager(_:didEndAnimatingFor:).

// Declare the map's gesture manager delegate
mapView.gestures.delegate = self
...

// Conform to the GestureManagerDelegate protocol
extension BasicMapExample: GestureManagerDelegate {
    public func gestureManager(_ gestureManager: GestureManager, didBegin gestureType: GestureType) {
        print("\(gestureType) didBegin")
    }

    public func gestureManager(_ gestureManager: GestureManager, didEnd gestureType: GestureType, willAnimate: Bool) {
        print("\(gestureType) didEnd")
    }

    public func gestureManager(_ gestureManager: GestureManager, didEndAnimatingFor gestureType: GestureType) {
        print("didEndAnimatingFor \(gestureType)")
    }
}

Specify custom behavior​

There are a variety of techniques available to change how the map responds to a built-in gesture, repurpose a built-in gesture for a non-map behavior, or allow manipulating the map with an entirely new type of gesture, including:

Your gesture handling code can programmatically update the map camera using the MapboxMap APIs (mapView.mapboxMap).

Removing any default target/action pairs from the built-in gesture recognizers or modifying their delegate properties is discouraged.

Additional Developer Resources
Was this page helpful?