User interaction

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.

GestureManager also has a single tap gesture that is used to detect taps on annotations. You can add a target-action pair to this gesture recognizer to be notified when a single tap occurs on the map. For more details on annotation-related gestures, see the Markers and Annotations guide’s Interactivity section.

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.