MapboxMap

public final class MapboxMap : StyleManager

Provides access to the map model, including the camera, style, observable map events, and querying rendered features.

If you have a MapView you can access the MapboxMap instance via mapboxMap property.

Use style property to access runtime styling API, for example:

  mapboxMap.style.uri = .satelliteStreets

Use on-prefixed properties to subscribe to map events, for example:

   // Holds resources allocated for subscriptions.
   var cancelables = Set<AnyCancelable>()

   // Observe every occurrence of CameraChanged event.
   mapboxMap.onCameraChanged.observe { event in
        print("Current camera state: \(event.cameraState)")
   }.store(in: &cancelables)

   // Observe only the next occurrence of MapLoaded event.
   mapboxMap.onMapLoaded.observeNext { event in
       print("Map is loaded at: \(event.timeInterval.end)")
   }.store(in: &cancelables)

The AnyCancelable object returned from observe(_:) or observeNext(_:) holds the resources allocated for the subscription and can be used to cancel it. If the cancelable object is deallocated, the subscription will be cancelled immediately.

The simplified diagram of the events emitted by the map is displayed below.

┌─────────────┐               ┌─────────┐                   ┌──────────────┐
│ Application │               │   Map   │                   │ResourceLoader│
└──────┬──────┘               └────┬────┘                   └───────┬──────┘
       │                           │                                │
       ├───────setStyleURI────────▶│                                │
       │                           ├───────────get style───────────▶│
       │                           │                                │
       │                           │◀─────────style data────────────┤
       │                           │                                │
       │                           ├─parse style─┐                  │
       │                           │             │                  │
       │      StyleDataLoaded      ◀─────────────┘                  │
       │◀───────type: Style────────┤                                │
       │                           ├─────────get sprite────────────▶│
       │                           │                                │
       │                           │◀────────sprite data────────────┤
       │                           │                                │
       │                           ├──────parse sprite───────┐      │
       │                           │                         │      │
       │      StyleDataLoaded      ◀─────────────────────────┘      │
       │◀──────type: Sprite────────┤                                │
       │                           ├─────get source TileJSON(s)────▶│
       │                           │                                │
       │     SourceDataLoaded      │◀─────parse TileJSON data───────┤
       │◀─────type: Metadata───────┤                                │
       │                           │                                │
       │                           │                                │
       │      StyleDataLoaded      │                                │
       │◀──────type: Sources───────┤                                │
       │                           ├──────────get tiles────────────▶│
       │                           │                                │
       │◀───────StyleLoaded────────┤                                │
       │                           │                                │
       │     SourceDataLoaded      │◀─────────tile data─────────────┤
       │◀───────type: Tile─────────┤                                │
       │                           │                                │
       │                           │                                │
       │◀────RenderFrameStarted────┤                                │
       │                           ├─────render─────┐               │
       │                           │                │               │
       │                           ◀────────────────┘               │
       │◀───RenderFrameFinished────┤                                │
       │                           ├──render, all tiles loaded──┐   │
       │                           │                            │   │
       │                           ◀────────────────────────────┘   │
       │◀────────MapLoaded─────────┤                                │
       │                           │                                │
       │                           │                                │
       │◀─────────MapIdle──────────┤                                │
       │                    ┌ ─── ─┴─ ─── ┐                         │
       │                    │   offline   │                         │
       │                    └ ─── ─┬─ ─── ┘                         │
       │                           │                                │
       ├─────────setCamera────────▶│                                │
       │                           ├───────────get tiles───────────▶│
       │                           │                                │
       │                           │┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   │
       │◀─────────MapIdle──────────┤   waiting for connectivity  │  │
       │                           ││  Map renders cached data      │
       │                           │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘  │
       │                           │                                │

Important

MapboxMap should only be used from the main thread.


                    
                    
                    style

The style object supports run time styling.

Declaration

Swift

@available(*, deprecated, message: "Access style APIs directly from MapboxMap instance instead")
public var style: StyleManager { get }

Render loop

triggerRepaint()
Triggers a repaint of the map. Calling this method is typically unnecessary but may be needed if using a custom layer that needs to be redrawn independently of other map changes.
Declaration
Swift

public func triggerRepaint()

Style loading


                    
                    
                    loadStyle(_:transition:completion:)

Loads a style from a StyleURI, calling a completion closure when the style is fully loaded or there has been an error during load.

Declaration

Swift

public func loadStyle(_ styleURI: StyleURI,
                      transition: TransitionOptions? = nil,
                      completion: ((MapLoadingError?) -> Void)? = nil)

Parameters

`styleURI`	StyleURI to load
`transition`	Options for the style transition.
`completion`	Closure called when the style has been fully loaded. If style has failed to load a `MapLoadingError` is provided to the closure.


                    
                    
                    loadStyleURI(_:completion:)

Loads a style from a StyleURI, calling a completion closure when the style is fully loaded or there has been an error during load.

Declaration

Swift

@available(*, deprecated, renamed: "loadStyle")
public func loadStyleURI(_ styleURI: StyleURI, completion: ((MapLoadingError?) -> Void)? = nil)

Parameters

`styleURI`	StyleURI to load
`completion`	Closure called when the style has been fully loaded.


                    
                    
                    loadStyle(_:transition:completion:)

Loads a style from a JSON string, calling a completion closure when the style is fully loaded or there has been an error during load.

Declaration

Swift

public func loadStyle(_ JSON: String,
                      transition: TransitionOptions? = nil,
                      completion: ((MapLoadingError?) -> Void)? = nil)

Parameters

`JSON`	Style JSON string
`transition`	Options for the style transition.
`completion`	Closure called when the style has been fully loaded. If style has failed to load a `MapLoadingError` is provided to the closure.


                    
                    
                    loadStyleJSON(_:completion:)

Loads a style from a JSON string, calling a completion closure when the style is fully loaded or there has been an error during load.

Declaration

Swift

@available(*, deprecated, renamed: "loadStyle")
public func loadStyleJSON(_ JSON: String, completion: ((MapLoadingError?) -> Void)? = nil)

Parameters

`JSON`	Style JSON string
`completion`	Closure called when the style has been fully loaded. The `Result` type encapsulates the `Style` or error that occurred. See `MapLoadingError`

Prefetching

prefetchZoomDelta
When loading a map, if prefetchZoomDelta is set to any number greater than 0, the map will first request a tile for zoom - prefetchZoomDelta in an attempt to display a full map at lower resolution as quick as possible.

It will get clamped at the tile source minimum zoom. The default delta is 4.
Declaration
Swift

public var prefetchZoomDelta: UInt8 { get set }


                    
                    
                    setTileCacheBudget(_:)

The tile cache budget hint to be used by the map.

The budget can be given in tile units or in megabytes. A Map will do the best effort to keep memory allocations for a non essential resources within the budget.

If tile cache budget in megabytes is set, the engine will try to use ETC1 texture compression for raster layers, therefore, raster images with alpha channel will be rendered incorrectly.

If null is set, the tile cache budget in tile units will be dynamically calculated based on the current viewport size.

Declaration

Swift

public func setTileCacheBudget(_ tileCacheBudget: TileCacheBudget?)

Parameters


                                  tileCacheBudget

The tile cache budget hint to be used by the Map.

shouldRenderWorldCopies
Defines whether multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude.

If disabled, when the map is zoomed out far enough that a single representation of the world does not fill the map’s entire container, there will be blank space beyond 180 and -180 degrees longitude. In this case, features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level.

By default, shouldRenderWorldCopies is set to true.
Declaration
Swift

public var shouldRenderWorldCopies: Bool { get set }


                    
                    
                    elevation(at:)

Gets elevation for the given coordinate.

Note

Elevation is only available for the visible region on the screen.

Declaration

Swift

public func elevation(at coordinate: CLLocationCoordinate2D) -> Double?

Parameters


                                  coordinate

Coordinate for which to return the elevation.

Return Value

Elevation (in meters) multiplied by current terrain exaggeration, or empty if elevation for the coordinate is not available.

Camera Fitting


                    
                    
                    coordinateBounds(for:)

Transforms a view’s frame into a set of coordinate bounds

Declaration

Swift

public func coordinateBounds(for rect: CGRect) -> CoordinateBounds

Parameters


                                  rect

The rect whose bounds will be transformed into a set of map coordinate bounds.

Return Value

A CoordinateBounds object that represents the southwest and northeast corners of the view’s bounds.


                    
                    
                    rect(for:)

Transforms a set of map coordinate bounds to a CGRect relative to the MapView.

Declaration

Swift

public func rect(for coordinateBounds: CoordinateBounds) -> CGRect

Parameters


                                  coordinateBounds

The coordinateBounds that will be converted into a rect relative to the MapView

Return Value

A CGRect whose corners represent the vertices of a set of CoordinateBounds.

Debug options

debugOptions
The array of MapDebugOptions for the native map. Setting this property to an empty array disables previously enabled MapDebugOptions. The default value is an empty array.
Declaration
Swift

@available(*, deprecated, message: "Use mapView.debugOptions instead.") public var debugOptions: [MapDebugOptions] { get set }
options
Returns the map’s options
Declaration
Swift

public var options: MapOptions { get }


                    
                    
                    camera(for:padding:bearing:pitch:maxZoom:offset:)

Calculates a CameraOptions to fit a CoordinateBounds

This API isn’t supported by Globe projection.

Declaration

Swift

public func camera(for coordinateBounds: CoordinateBounds, // swiftlint:disable:this function_parameter_count
                   padding: UIEdgeInsets,
                   bearing: Double?,
                   pitch: Double?,
                   maxZoom: Double?,
                   offset: CGPoint?) -> CameraOptions

Parameters

`coordinateBounds`	The coordinate bounds that will be displayed within the viewport.
`padding`	The amount of padding to add to the given bounds when calculating the camera, in points. This is differnt from camera padding.
`bearing`	The new bearing to be used by the camera, in degrees (0°, 360°) clockwise from true north.
`pitch`	The new pitch to be used by the camera, in degrees (0°, 85°) with 0° being a top-down view.
`maxZoom`	The maximum zoom level to allow when the camera would transition to the specified bounds.
`offset`	The center of the given bounds relative to the map’s center, measured in points.

Return Value

A CameraOptions that fits the provided constraints


                    
                    
                    camera(for:padding:bearing:pitch:)

Calculates a CameraOptions to fit a list of coordinates.

This API isn’t supported by Globe projection.

Declaration

Swift

public func camera(for coordinates: [CLLocationCoordinate2D],
                   padding: UIEdgeInsets?,
                   bearing: Double?,
                   pitch: Double?) -> CameraOptions

Parameters

`coordinates`	Array of coordinates that should fit within the new viewport.
`padding`	The amount of padding to add to the given bounds when calculating the camera, in points. This is differnt from camera padding.
`bearing`	The new bearing to be used by the camera, in degrees (0°, 360°) clockwise from true north.
`pitch`	The new pitch to be used by the camera, in degrees (0°, 85°) with 0° being a top-down view.

Return Value

A CameraOptions that fits the provided constraints


                    
                    
                    camera(for:camera:rect:)

Calculates a CameraOptions to fit a list of coordinates into a sub-rect of the map.

Adjusts the zoom of camera to fit coordinates into rect.

Returns the provided camera with zoom adjusted to fit coordinates into rect, so that the coordinates on the left, top and right of the effective camera center at the principal point of the projection (defined by padding) fit into the rect.

This API isn’t supported by Globe projection.

Note

This method may fail if the principal point of the projection is not inside rect or if there is insufficient screen space, defined by principal point and rect, to fit the geometry.

Declaration

Swift

public func camera(for coordinates: [CLLocationCoordinate2D],
                   camera: CameraOptions,
                   rect: CGRect) -> CameraOptions

Parameters

`coordinates`	The coordinates to frame within `rect`.
`camera`	The camera for which the zoom should be adjusted to fit `coordinates`. `camera.center` must be non-nil.
`rect`	The rectangle inside of the map that should be used to frame `coordinates`.

Return Value

A CameraOptions that fits the provided constraints, or cameraOptions if an error occurs.


                    
                    
                    camera(for:padding:bearing:pitch:)

Calculates a CameraOptions to fit a geometry

This API isn’t supported by Globe projection.

Declaration

Swift

public func camera(for geometry: Geometry,
                   padding: UIEdgeInsets,
                   bearing: CGFloat?,
                   pitch: CGFloat?) -> CameraOptions

Parameters

`geometry`	The geoemtry that will be displayed within the viewport.
`padding`	The new padding to be used by the camera.
`bearing`	The new bearing to be used by the camera.
`pitch`	The new pitch to be used by the camera.

Return Value

A CameraOptions that fits the provided constraints

CameraOptions to CoordinateBounds


                    
                    
                    coordinateBounds(for:)

Returns the coordinate bounds corresponding to a given CameraOptions

This API isn’t supported by Globe projection.

Declaration

Swift

public func coordinateBounds(for camera: CameraOptions) -> CoordinateBounds

Parameters


                                  camera

The camera for which the coordinate bounds will be returned.

Return Value

CoordinateBounds for the given CameraOptions


                    
                    
                    coordinateBoundsUnwrapped(for:)

Returns the unwrapped coordinate bounds to a given CameraOptions.

This function is particularly useful, if the camera shows the antimeridian.

This API isn’t supported by Globe projection.

Declaration

Swift

public func coordinateBoundsUnwrapped(for camera: CameraOptions) -> CoordinateBounds

Parameters


                                  camera

The camera for which the coordinate bounds will be returned.

Return Value

CoordinateBounds for the given CameraOptions.


                    
                    
                    coordinateBoundsZoom(for:)

Returns the coordinate bounds and zoom for a given CameraOptions.

This API isn’t supported by Globe projection.

Declaration

Swift

public func coordinateBoundsZoom(for camera: CameraOptions) -> CoordinateBoundsZoom

Parameters


                                  camera

The camera for which the CoordinateBoundsZoom will be returned.

Return Value

CoordinateBoundsZoom for the given CameraOptions


                    
                    
                    coordinateBoundsZoomUnwrapped(for:)

Returns the unwrapped coordinate bounds and zoom for a given CameraOptions.

This function is particularly useful, if the camera shows the antimeridian.

This API isn’t supported by Globe projection.

Declaration

Swift

public func coordinateBoundsZoomUnwrapped(for camera: CameraOptions) -> CoordinateBoundsZoom

Parameters


                                  camera

The camera for which the CoordinateBoundsZoom will be returned.

Return Value

CoordinateBoundsZoom for the given CameraOptions

Screen coordinate conversion


                    
                    
                    coordinate(for:)

Converts a point in the mapView’s coordinate system to a geographic coordinate. The point must exist in the coordinate space of the MapView

This API isn’t supported by Globe projection.

Declaration

Swift

public func coordinate(for point: CGPoint) -> CLLocationCoordinate2D

Parameters


                                  point

The point to convert. Must exist in the coordinate space of the MapView

Return Value

A CLLocationCoordinate that represents the geographic location of the point.


                    
                    
                    point(for:)

Converts a map coordinate to a CGPoint, relative to the MapView.

This API isn’t supported by Globe projection.

Declaration

Swift

public func point(for coordinate: CLLocationCoordinate2D) -> CGPoint

Parameters


                                  coordinate

The coordinate to convert.

Return Value

A CGPoint relative to the UIView. If the point is outside of the bounds of MapView the returned point contains -1.0 for both coordinates.


                    
                    
                    points(for:)

Converts map coordinates to an array of CGPoint, relative to the MapView.

This API isn’t supported by Globe projection.

Declaration

Swift

public func points(for coordinates: [CLLocationCoordinate2D]) -> [CGPoint]

Parameters


                                  coordinates

The coordinate to convert.

Return Value

An array of CGPoint relative to the UIView. If a coordinate's point is outside of map view's bounds, it will be(-1, -1)`


                    
                    
                    coordinates(for:)

Converts points in the mapView’s coordinate system to geographic coordinates. The points must exist in the coordinate space of the MapView.

This API isn’t supported by Globe projection.

Declaration

Swift

public func coordinates(for points: [CGPoint]) -> [CLLocationCoordinate2D]

Parameters


                                  point

The point to convert. Must exist in the coordinate space of the MapView

Return Value

A CLLocationCoordinate that represents the geographic location of the point.

Camera options setters/getters


                    
                    
                    setCamera(to:)

Changes the map view by any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not passed via the camera options argument. It is not guaranteed that the provided CameraOptions will be set, the map may apply constraints resulting in a different CameraState.

Important

This method does not cancel existing animations. Call CameraAnimationsManager.cancelAnimations()to cancel existing animations.

Declaration

Swift

public func setCamera(to cameraOptions: CameraOptions)

Parameters


                                  cameraOptions

New camera options

cameraState
Returns the current camera state
Declaration
Swift

public var cameraState: CameraState { get }


                    
                    
                    freeCameraOptions

Sets/get the map view with the free camera options.

FreeCameraOptions provides more direct access to the underlying camera entity. For backwards compatibility the state set using this API must be representable with CameraOptions as well. Parameters are clamped to a valid range or discarded as invalid if the conversion to the pitch and bearing presentation is ambiguous. For example orientation can be invalid if it leads to the camera being upside down or the quaternion has zero length.

Declaration

Swift

public var freeCameraOptions: FreeCameraOptions { get set }

Parameters


                                  freeCameraOptions

The free camera options to set.

cameraBounds
Returns the bounds of the map.
Declaration
Swift

public var cameraBounds: CameraBounds { get }


                    
                    
                    setCameraBounds(with:)

Sets the bounds of the map.

Throws

MapError

Declaration

Swift

public func setCameraBounds(with options: CameraBoundsOptions) throws

Parameters


                                  options

New camera bounds. Nil values will not take effect.

Drag API


                    
                    
                    dragCameraOptions(from:to:)

Calculates target point where camera should move after drag. The method should be called after dragStart and before dragEnd.

Declaration

Swift

public func dragCameraOptions(from: CGPoint, to: CGPoint) -> CameraOptions

Parameters

`fromPoint`	The point from which the map is dragged.
`toPoint`	The point to which the map is dragged.

Return Value

The camera options object showing end point.

Gesture and Animation Flags

beginAnimation()
If implementing a custom animation mechanism, call this method when the animation begins. Must always be paired with a corresponding call to endAnimation()
Declaration
Swift

public func beginAnimation()
endAnimation()
If implementing a custom animation mechanism, call this method when the animation ends. Must always be paired with a corresponding call to beginAnimation()
Declaration
Swift

public func endAnimation()
beginGesture()
If implementing a custom gesture, call this method when the gesture begins. Must always be paired with a corresponding call to endGesture()
Declaration
Swift

public func beginGesture()
endGesture()
If implementing a custom gesture, call this method when the gesture ends. Must always be paired with a corresponding call to beginGesture()
Declaration
Swift

public func endGesture()

MapFeatureQueryable


                    
                    
                    queryRenderedFeatures(with:options:completion:)

Queries the map for rendered features.

Declaration

Swift

@discardableResult
public func queryRenderedFeatures(with shape: [CGPoint], options: RenderedQueryOptions? = nil, completion: @escaping (Result<[QueriedRenderedFeature], Error>) -> Void) -> Cancelable

Parameters

`shape`	Screen point coordinates (point, line string or box) to query for rendered features.
`options`	Options for querying rendered features.
`completion`	Callback called when the query completes.


                    
                    
                    queryRenderedFeatures(with:options:completion:)

Queries the map for rendered features.

Declaration

Swift

@discardableResult
public func queryRenderedFeatures(with rect: CGRect, options: RenderedQueryOptions? = nil, completion: @escaping (Result<[QueriedRenderedFeature], Error>) -> Void) -> Cancelable

Parameters

`rect`	Screen rect to query for rendered features.
`options`	Options for querying rendered features.
`completion`	Callback called when the query completes.


                    
                    
                    queryRenderedFeatures(with:options:completion:)

Queries the map for rendered features.

Declaration

Swift

@discardableResult
public func queryRenderedFeatures(with point: CGPoint, options: RenderedQueryOptions? = nil, completion: @escaping (Result<[QueriedRenderedFeature], Error>) -> Void) -> Cancelable

Parameters

`point`	Screen point at which to query for rendered features.
`options`	Options for querying rendered features.
`completion`	Callback called when the query completes.


                    
                    
                    querySourceFeatures(for:options:completion:)

Queries the map for source features.

Declaration

Swift

@discardableResult
public func querySourceFeatures(for sourceId: String,
                                options: SourceQueryOptions,
                                completion: @escaping (Result<[QueriedSourceFeature], Error>) -> Void) -> Cancelable

Parameters

`sourceId`	Style source identifier used to query for source features.
`options`	Options for querying source features.
`completion`	Callback called when the query completes.


                    
                    
                    getGeoJsonClusterLeaves(forSourceId:feature:limit:offset:completion:)

Returns all the leaves (original points) of a cluster (given its cluster_id) from a GeoJSON source, with pagination support: limit is the number of leaves to return (set to Infinity for all points), and offset is the amount of points to skip (for pagination).

Declaration

Swift

@discardableResult
public func getGeoJsonClusterLeaves(forSourceId sourceId: String,
                                    feature: Feature,
                                    limit: UInt64 = 10,
                                    offset: UInt64 = 0,
                                    completion: @escaping (Result<FeatureExtensionValue, Error>) -> Void) -> Cancelable

Parameters

`sourceId`	The identifier of the source to query.
`feature`	Feature to look for in the query.
`limit`	the number of points to return from the query, default to 10
`offset`	the amount of points to skip, default to 0
`completion`	The result could be a feature extension value containing either a value (expansion-zoom) or a feature collection (children or leaves). An error is passed if the operation was not successful.


                    
                    
                    getGeoJsonClusterChildren(forSourceId:feature:completion:)

Returns the children (original points or clusters) of a cluster (on the next zoom level) given its id (cluster_id value from feature properties) from a GeoJSON source.

Declaration

Swift

@discardableResult
public func getGeoJsonClusterChildren(forSourceId sourceId: String,
                                      feature: Feature,
                                      completion: @escaping (Result<FeatureExtensionValue, Error>) -> Void) -> Cancelable

Parameters

`sourceId`	The identifier of the source to query.
`feature`	Feature to look for in the query.
`completion`	The result could be a feature extension value containing either a value (expansion-zoom) or a feature collection (children or leaves). An error is passed if the operation was not successful.


                    
                    
                    getGeoJsonClusterExpansionZoom(forSourceId:feature:completion:)

Returns the zoom on which the cluster expands into several children (useful for “click to zoom” feature) given the cluster’s cluster_id (cluster_id value from feature properties) from a GeoJSON source.

Declaration

Swift

@discardableResult
public func getGeoJsonClusterExpansionZoom(forSourceId sourceId: String,
                                           feature: Feature,
                                           completion: @escaping (Result<FeatureExtensionValue, Error>) -> Void) -> Cancelable

Parameters

`sourceId`	The identifier of the source to query.
`feature`	Feature to look for in the query.
`completion`	The result could be a feature extension value containing either a value (expansion-zoom) or a feature collection (children or leaves). An error is passed if the operation was not successful.

Map Event handling

onMapLoaded
The style has been fully loaded, and the map has rendered all visible tiles.
Declaration
Swift

public var onMapLoaded: Signal<MapLoaded> { get }
onMapLoadingError
An error that has occurred while loading the Map. The type property defines what resource could not be loaded and the message property will contain a descriptive error message. In case of source or tile loading errors, sourceID or tileID will contain the identifier of the source failing.
Declaration
Swift

public var onMapLoadingError: Signal<MapLoadingError> { get }
onStyleLoaded
The requested style has been fully loaded, including the style, specified sprite and sources’ metadata.

The style specified sprite would be marked as loaded even with sprite loading error (an error will be emitted via onMapLoadingError). Sprite loading error is not fatal and we don’t want it to block the map rendering, thus this event will still be emitted if style and sources are fully loaded.
Declaration
Swift

public var onStyleLoaded: Signal<StyleLoaded> { get }
onStyleDataLoaded
The requested style data has been loaded. The type property defines what kind of style data has been loaded. Event may be emitted synchronously, for example, when loadStyle(_:transition:completion:) is used to load style.

Based on an event data type property value, following use-cases may be implemented:
- style: Style is parsed, style layer properties could be read and modified, style layers and sources could be added or removed before rendering is started.
- sprite: Style’s sprite sheet is parsed and it is possible to add or update images.
- sources: All sources defined by the style are loaded and their properties could be read and updated if needed.
Declaration
Swift

public var onStyleDataLoaded: Signal<StyleDataLoaded> { get }
onCameraChanged
The camera has changed. This event is emitted whenever the visible viewport changes due to the MapView’s size changing or when the camera is modified by calling camera methods. The event is emitted synchronously, so that an updated camera state can be fetched immediately.
Declaration
Swift

public var onCameraChanged: Signal<CameraChanged> { get }
onMapIdle
The map has entered the idle state. The map is in the idle state when there are no ongoing transitions and the map has rendered all requested non-volatile tiles. The event will not be emitted if animation is in progress (see beginAnimation(), endAnimation()) and / or gesture is in progress (see beginGesture(), endGesture()).
Declaration
Swift

public var onMapIdle: Signal<MapIdle> { get }
onSourceAdded
The source has been added with addSource(_:dataId:) or addSource(withId:properties:). The event is emitted synchronously, therefore, it is possible to immediately read added source’s properties.
Declaration
Swift

public var onSourceAdded: Signal<SourceAdded> { get }
onSourceRemoved
The source has been removed with removeSource(withId:). The event is emitted synchronously, thus, allSourceIdentifiers will be in sync when the observer receives the notification.
Declaration
Swift

public var onSourceRemoved: Signal<SourceRemoved> { get }
onSourceDataLoaded
A source data has been loaded. Event may be emitted synchronously in cases when source’s metadata is available when source is added to the style.

The dataID property defines the source id.

The type property defines if source’s metadata (e.g., TileJSON) or tile has been loaded. The property of metadata value might be useful to identify when particular source’s metadata is loaded, thus all source’s properties are readable and can be updated before map will start requesting data to be rendered.

The loaded property will be set to true if all source’s data required for visible viewport of the map, are loaded. The tileID property defines the tile id if the type field equals tile. The dataID property will be returned if it has been set for this source.
Declaration
Swift

public var onSourceDataLoaded: Signal<SourceDataLoaded> { get }
onStyleImageMissing
A style has a missing image. This event is emitted when the map renders visible tiles and one of the required images is missing in the sprite sheet. Subscriber has to provide the missing image by calling addImage(_:id:sdf:contentInsets:).
Declaration
Swift

public var onStyleImageMissing: Signal<StyleImageMissing> { get }
onStyleImageRemoveUnused
An image added to the style is no longer needed and can be removed using removeImage(withId:).
Declaration
Swift

public var onStyleImageRemoveUnused: Signal<StyleImageRemoveUnused> { get }


                    
                    
                    onRenderFrameStarted

The map started rendering a frame.

Declaration

Swift

public var onRenderFrameStarted: Signal<RenderFrameStarted> { get }

onRenderFrameFinished
The map finished rendering a frame. The renderMode property tells whether the map has all data (full) required to render the visible viewport. The needsRepaint property provides information about ongoing transitions that trigger map repaint. The placementChanged property tells if the symbol placement has been changed in the visible viewport.
Declaration
Swift

public var onRenderFrameFinished: Signal<RenderFrameFinished> { get }
onResourceRequest
The ResourceRequest event allows client to observe resource requests made by a map or snapshotter.
Declaration
Swift

public var onResourceRequest: Signal<ResourceRequest> { get }
subscript(_:)
Returns a Signal that allows to subscribe to the event with specified string name. This method is reserved for the future use.
Declaration
Swift

@_documentation(visibility: public) @_spi(Experimental) public subscript(eventName: String) -> Signal<GenericEvent> { get }


                    
                    
                    onNext(event:handler:)

Listen to a single occurrence of a Map event.

This will observe the next (and only the next) event of the specified type. After observation, the underlying subscriber will unsubscribe from the map or snapshotter.

If you need to unsubscribe before the event fires, call cancel() on the returned Cancelable object.

Declaration

Swift

@available(*, deprecated, message: "Use mapboxMap.on<eventType>.observeNext instead.")
@discardableResult
public func onNext<Payload>(event: MapEventType<Payload>, handler: @escaping (Payload) -> Void) -> Cancelable

Parameters

`eventType`	The event type to listen to.
`handler`	The closure to execute when the event occurs.

Return Value

A Cancelable object that you can use to stop listening for the event. This is especially important if you have a retain cycle in the handler.


                    
                    
                    onEvery(event:handler:)

Listen to multiple occurrences of a Map event.

Declaration

Swift

@available(*, deprecated, message: "Use mapboxMap.on<eventType>.observe instead.")
@discardableResult
public func onEvery<Payload>(event: MapEventType<Payload>, handler: @escaping (Payload) -> Void) -> Cancelable

Parameters

`eventType`	The event type to listen to.
`handler`	The closure to execute when the event occurs.

Return Value

A Cancelable object that you can use to stop listening for events. This is especially important if you have a retain cycle in the handler.

Map data clearing


                    
                    
                    clearData(completion:)

Clears temporary map data.

Clears temporary map data from the data path defined in the given resource options. Useful to reduce the disk usage or in case the disk cache contains invalid data.

Note

Calling this API will affect all maps that use the same data path and does not affect persistent map data like offline style packages.

Declaration

Swift

public static func clearData(completion: @escaping (Error?) -> Void)

Parameters


                                  completion

Called once the request is complete

Feature State


                    
                    
                    setFeatureState(sourceId:sourceLayerId:featureId:state:callback:)

Update the state map of a feature within a style source. Update entries in the state map of a given feature within a style source. Only entries listed in the state map will be updated. An entry in the feature state map that is not listed in state will retain its previous value.

Declaration

Swift

@discardableResult
public func setFeatureState(sourceId: String, sourceLayerId: String? = nil, featureId: String, state: [String : Any], callback: @escaping (Result<NSNull, Error>) -> Void) -> Cancelable

Parameters

`sourceId`	Style source identifier
`sourceLayerId`	Style source layer identifier (for multi-layer sources such as vector sources). Defaults to `nil`.
`featureId`	Identifier of the feature whose state should be updated
`state`	Map of entries to update with their respective new values
`callback`	The `feature state operation callback` called when the operation completes or ends.

Return Value

A Cancelable object that could be used to cancel the pending operation.


                    
                    
                    getFeatureState(sourceId:sourceLayerId:featureId:callback:)

Get the state map of a feature within a style source.

Declaration

Swift

@discardableResult
public func getFeatureState(sourceId: String, sourceLayerId: String? = nil, featureId: String, callback: @escaping (Result<[String : Any], Error>) -> Void) -> Cancelable

Parameters

`sourceId`	Style source identifier.
`sourceLayerId`	Style source layer identifier (for multi-layer sources such as vector sources).
`featureId`	Identifier of the feature whose state should be queried.
`callback`	Feature’s state map or an empty map if the feature could not be found.

Return Value

A Cancelable object that could be used to cancel the pending query.


                    
                    
                    removeFeatureState(sourceId:sourceLayerId:featureId:stateKey:callback:)

Removes entries from a feature state object. Remove a specified property or all property from a feature’s state object, depending on the value of stateKey.

Declaration

Swift

@discardableResult
public func removeFeatureState(sourceId: String, sourceLayerId: String? = nil, featureId: String, stateKey: String? = nil, callback: @escaping (Result<NSNull, Error>) -> Void) -> Cancelable

Parameters

`sourceId`	The style source identifier
`sourceLayerId`	The style source layer identifier (for multi-layer sources such as vector sources). Defaults to `nil`.
`featureId`	The feature identifier of the feature whose state should be removed.
`stateKey`	The key of the property to remove. If `nil`, all feature’s state object properties are removed. Defaults to `nil`.
`callback`	The `feature state operation callback` called when the operation completes or ends.

Return Value

A cancelable object that could be used to cancel the pending operation.


                    
                    
                    resetFeatureStates(sourceId:sourceLayerId:callback:)

Reset all the feature states within a style source. Remove all feature state entries from the specified style source or source layer. Note that updates to feature state are asynchronous, so changes made by this method might not be immediately visible using getStateFeature.

Declaration

Swift

@discardableResult
public func resetFeatureStates(sourceId: String, sourceLayerId: String? = nil, callback: @escaping (Result<NSNull, Error>) -> Void) -> Cancelable

Parameters

`sourceId`	The style source identifier
`sourceLayerId`	The style source layer identifier (for multi-layer sources such as vector sources). Defaults to `nil`.
`callback`	The `feature state operation callback` called when the operation completes or ends.

Return Value

A cancelable object that could be used to cancel the pending operation.

TileCover


                    
                    
                    tileCover(for:)

Returns array of tile identifiers that cover current map camera.

Declaration

Swift

@_documentation(visibility: public)
@_spi(Experimental)
public func tileCover(for options: TileCoverOptions) -> [CanonicalTileID]

Map Recorder


                    
                    
                    makeRecorder()

Create a MapRecorder to record the current MapboxMap

Declaration

Swift

@_spi(Experimental)
public final func makeRecorder() throws -> MapRecorder