Style

 
public final class Style : StyleProtocol

Style provides access to the APIs used to dynamically modify the map’s style. Use it to read and write layers, sources, and images. Obtain the Style instance for a MapView via MapView.mapboxMap.style.

Important

Style should only be used from the main thread.

  • Undocumented

    Declaration

    Swift

    public weak var styleManager: StyleManager! { get }

Layers

  • Adds a layer to the map

    Throws

    StyleError if there is a problem adding the given layer at the given position.

    Declaration

    Swift

    public func addLayer(_ layer: Layer, layerPosition: LayerPosition? = nil) throws

    Parameters

    layer

    The layer to apply on the map
    layerPosition

    Position to add the layer in the stack of layers on the map. Defaults to the top layer.

  • Adds a persistent layer to the map. Persistent layers are valid across style changes.

    Throws

    StyleError if there is a problem adding the persistent layer.

    Declaration

    Swift

    public func addPersistentLayer(_ layer: Layer, layerPosition: LayerPosition? = nil) throws

    Parameters

    layer

    The layer to apply on the map
    layerPosition

    Position to add the layer in the stack of layers on the map. Defaults to the top layer.

  • Moves a layer to a new layer position in the style.

    Throws

    StyleError on failure, or NSError with a _domain of “com.mapbox.bindgen”

    Declaration

    Swift

    public func moveLayer(withId id: String, to position: LayerPosition) throws

    Parameters

    layerId

    The layer to move
    position

    Position to move the layer in the stack of layers on the map. Defaults to the top layer.

  • Gets a layer from the map

    Throws

    StyleError if there is a problem getting the layer data.

    Throws

    TypeConversionError is there is a problem decoding the layer data to the given type.

    Declaration

    Swift

    public func layer<T>(withId id: String, type: T.Type) throws -> T where T : Layer

    Parameters

    id

    The id of the layer to be fetched
    type

    The type of the layer that will be fetched

    Return Value

    The fully formed layer object of type equal to type

  • Gets a layer from the map.

    This function is useful if you do not know the concrete type of the layer you are fetching, or don’t need to know for your situation.

    Throws

    Type conversion errors

    Declaration

    Swift

    public func layer(withId id: String) throws -> Layer

    Parameters

    layerID

    The id of the layer to be fetched

    Return Value

    The fully formed layer object.

  • Updates a layer that exists in the style already

    Throws

    TypeConversionError if there is a problem getting a layer data.

    Throws

    StyleError if there is a problem updating the layer.

    Throws

    An error when executing update block.

    Declaration

    Swift

    public func updateLayer<T>(withId id: String,
                           type: T.Type,
                           update: (inout T) throws -> Void) throws where T: Layer

    Parameters

    id

    identifier of layer to update
    type

    Type of the layer
    update

    Closure that mutates a layer passed to it

Sources

  • Adds a source to the map

    Throws

    StyleError if there is a problem adding the source.

    Declaration

    Swift

    public func addSource(_ source: Source, id: String, dataId: String? = nil) throws

    Parameters

    source

    The source to add to the map.
    identifier

    A unique source identifier.
    dataId

    An optional data ID to filter MapEvents.sourceDataLoaded to only the specified data source. /// Applies only to GeoJSONSources

  • Retrieves a source from the map

    Throws

    StyleError if there is a problem getting the source data.

    Throws

    TypeConversionError if there is a problem decoding the source data to the given type.

    Declaration

    Swift

    public func source<T>(withId id: String, type: T.Type) throws -> T where T : Source

    Parameters

    id

    The id of the source to retrieve
    type

    The type of the source

    Return Value

    The fully formed source object of type equal to type.

  • Retrieves a source from the map

    This function is useful if you do not know the concrete type of the source you are fetching, or don’t need to know for your situation.

    Throws

    StyleError if there is a problem getting the source data.

    Throws

    TypeConversionError if there is a problem decoding the source of given id.

    Declaration

    Swift

    public func source(withId id: String) throws -> Source

    Parameters

    id

    The id of the source to retrieve.

    Return Value

    The fully formed source object.

  • Updates the data property of a given GeoJSONSource with a new value conforming to the GeoJSONObject protocol.

    Throws

    StyleError if there is a problem when updating GeoJSON source.

    Attention

    This method is only effective with sources of GeoJSONSource type, and cannot be used to update other source types.

    Declaration

    Swift

    public func updateGeoJSONSource(withId id: String, geoJSON: GeoJSONObject, dataId: String? = nil) throws

    Parameters

    id

    The identifier representing the GeoJSON source.
    geoJSON

    The new GeoJSON to be associated with the source data. i.e. a feature or feature collection.
    dataId

    An optional data ID to filter MapEvents.sourceDataLoaded to only the specified data source

  • true if and only if the style JSON contents, the style specified sprite, and sources are all loaded, otherwise returns false.

    Declaration

    Swift

    public var isLoaded: Bool { get }
  • uri

    Get or set the style URI

    Setting a new style is asynchronous. In order to get the result of this operation, listen to MapEvents.styleDataLoaded, MapEvents.styleLoaded.

    Attention

    This method should be called on the same thread where the MapboxMap object is initialized.

    Declaration

    Swift

    public var uri: StyleURI? { get set }

  • Get or set the style via a JSON serialization string

    Attention

    This method should be called on the same thread where the MapboxMap object is initialized.

    Declaration

    Swift

    public var JSON: String { get set }

  • The map style‘s default camera, if any, or a default camera otherwise. The map style default camera is defined as follows:

    The style default camera is re-evaluated when a new style is loaded. Values default to 0.0 if they are not defined in the style.

    Declaration

    Swift

    public var defaultCamera: CameraOptions { get }

  • Get or set the map style‘s transition options.

    By default, the style parser will attempt to read the style default transition, if any, falling back to a 0.3 s transition otherwise.

    Overridden transitions are reset once a new style has been loaded. To customize the transition used when switching styles, set this property after MapEvents.EventKind.styleDataLoaded where Event.type == "style" and before MapEvents.EventKind.styleDataLoaded where Event.type == "sprite" and where Event.type == "sources".

    See also

    onNext(_:handler:)

    Declaration

    Swift

    public var transition: TransitionOptions { get set }

Layers

  • Adds a new style layer given its JSON properties

    Runtime style layers are valid until they are either removed or a new style is loaded.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addLayer(with properties: [String : Any], layerPosition: LayerPosition?) throws

    Parameters

    properties

    A JSON dictionary of style layer properties.
    layerPosition

    Position to add the layer in the stack of layers on the map. Defaults to the top layer.

  • Adds a new persistent style layer given its JSON properties

    Persistent style layers remain valid across style reloads.

    Throws

    An error describing why the operation was unsuccessful

    Declaration

    Swift

    public func addPersistentLayer(with properties: [String : Any], layerPosition: LayerPosition?) throws

    Parameters

    properties

    A JSON dictionary of style layer properties
    layerPosition

    Position to add the layer in the stack of layers on the map. Defaults to the top layer.

  • Returns true if the id passed in is associated to a persistent layer

    Declaration

    Swift

    public func isPersistentLayer(id: String) throws -> Bool

    Parameters

    id

    The layer identifier to test

  • Adds a new persistent style custom layer.

    Persistent style layers are valid across style reloads.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addPersistentCustomLayer(withId id: String, layerHost: CustomLayerHost, layerPosition: LayerPosition?) throws

    Parameters

    id

    Style layer id.
    layerHost

    Style custom layer host.
    layerPosition

    Position to add the layer in the stack of layers on the map. Defaults to the top layer.

  • Adds a new style custom layer.

    Runtime style layers are valid until they are either removed or a new style is loaded.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addCustomLayer(withId id: String, layerHost: CustomLayerHost, layerPosition: LayerPosition?) throws

    Parameters

    id

    Style layer id.
    layerHost

    Style custom layer host.
    layerPosition

    Position to add the layer in the stack of layers on the map. Defaults to the top layer.

  • Removes an existing style layer

    Runtime style layers are valid until they are either removed or a new style is loaded.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func removeLayer(withId id: String) throws

    Parameters

    id

    Identifier of the style layer to remove.

  • Checks whether a given style layer exists.

    Runtime style layers are valid until they are either removed or a new style is loaded.

    Declaration

    Swift

    public func layerExists(withId id: String) -> Bool

    Parameters

    id

    Style layer identifier.

    Return Value

    true if the given style layer exists, false otherwise.

  • The ordered list of the current style layers’ identifiers and types

    Declaration

    Swift

    public var allLayerIdentifiers: [LayerInfo] { get }

Layer Properties

  • Gets the value of style layer property.

    Declaration

    Swift

    public func layerPropertyValue(for layerId: String, property: String) -> Any

    Parameters

    layerId

    Style layer identifier.
    property

    Style layer property name.

    Return Value

    The value of the property in the layer with layerId.

  • Gets the value of style layer property.

    Declaration

    Swift

    public func layerProperty(for layerId: String, property: String) -> StylePropertyValue

    Parameters

    layerId

    Style layer identifier.
    property

    Style layer property name.

    Return Value

    The value of the property in the layer with layerId.

  • Sets a JSON value to a style layer property.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setLayerProperty(for layerId: String, property: String, value: Any) throws

    Parameters

    layerId

    Style layer identifier.
    property

    Style layer property name.
    value

    Style layer property value.

  • Gets the default value of style layer property.

    Declaration

    Swift

    public static func layerPropertyDefaultValue(for layerType: LayerType, property: String) -> StylePropertyValue

    Parameters

    layerType

    Style layer type.
    property

    Style layer property name.

    Return Value

    The default value of the property for the layers with type layerType.

  • Gets the properties for a style layer.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func layerProperties(for layerId: String) throws -> [String : Any]

    Parameters

    layerId

    layer id.

    Return Value

    JSON dictionary representing the layer properties

  • Sets style layer properties.

    This method can be used to perform batch update for a style layer properties. The structure of a provided properties value must conform to the format for a corresponding layer type.

    Modification of a layer identifier and/or layer type is not allowed.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setLayerProperties(for layerId: String, properties: [String : Any]) throws

    Parameters

    layerId

    Style layer identifier.
    properties

    JSON dictionary representing the updated layer properties.

Sources

  • Adds a new style source.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/#sources

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addSource(withId id: String, properties: [String : Any]) throws

    Parameters

    id

    An identifier for the style source.
    properties

    A JSON dictionary of style source properties.

  • Removes an existing style source.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func removeSource(withId id: String) throws

    Parameters

    id

    Identifier of the style source to remove.

  • Checks whether a given style source exists.

    Declaration

    Swift

    public func sourceExists(withId id: String) -> Bool

    Parameters

    id

    Style source identifier.

    Return Value

    true if the given source exists, false otherwise.

  • The ordered list of the current style sources’ identifiers and types. Identifiers for custom vector sources will not be included

    Declaration

    Swift

    public var allSourceIdentifiers: [SourceInfo] { get }

Source properties

  • Gets the value of style source property.

    Declaration

    Swift

    public func sourceProperty(for sourceId: String, property: String) -> StylePropertyValue

    Parameters

    sourceId

    Style source identifier.
    property

    Style source property name.

    Return Value

    The value of the property in the source with sourceId.

  • Sets a value to a style source property.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setSourceProperty(for sourceId: String, property: String, value: Any) throws

    Parameters

    sourceId

    Style source identifier.
    property

    Style source property name.
    value

    Style source property value (JSON value)

  • Gets style source properties.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func sourceProperties(for sourceId: String) throws -> [String : Any]

    Parameters

    sourceId

    Style source identifier

    Return Value

    JSON dictionary representing the layer properties

  • Sets style source properties.

    This method can be used to perform batch update for a style source properties. The structure of a provided properties value must conform to the format for a corresponding source type. Modification of a source type is not allowed.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setSourceProperties(for sourceId: String, properties: [String : Any]) throws

    Parameters

    sourceId

    Style source identifier
    properties

    A JSON dictionary of Style source properties

  • Gets the default value of style source property.

    Declaration

    Swift

    public static func sourcePropertyDefaultValue(for sourceType: String, property: String) -> StylePropertyValue

    Parameters

    sourceType

    Style source type.
    property

    Style source property name.

    Return Value

    The default value for the named property for the sources with type sourceType.

Image source

Style images

  • Adds an image to be used in the style.

    This API can also be used for updating an image. If the image id was already added, it gets replaced by the new image.

    The image can be used in icon-image, fill-pattern, and line-pattern.

    For more information on how stretchX and stretchY parameters affect image stretching see this Mapbox GL-JS example.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addImage(_ image: UIImage,
                     id: String,
                     sdf: Bool = false,
                     stretchX: [ImageStretches],
                     stretchY: [ImageStretches],
                     content: ImageContent? = nil) throws

    Parameters

    image

    Image to add.
    id

    ID of the image.
    sdf

    Option to treat whether image is SDF(signed distance field) or not. Setting this to true allows template images to be recolored. The default value is false.
    stretchX

    An array of two-element arrays, consisting of two numbers that represent the from position and the to position of areas that can be stretched horizontally.
    stretchY

    An array of two-element arrays, consisting of two numbers that represent the from position and the to position of areas that can be stretched vertically.
    content

    An array of four numbers, with the first two specifying the left, top corner, and the last two specifying the right, bottom corner. If present, and if the icon uses icon-text-fit, the symbol’s text will be fit inside the content box.

  • Adds an image to be used in the style.

    If the image has non-zero UIImage.capInsets it will be stretched accordingly, regardless of the value in UIImage.resizingMode.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addImage(_ image: UIImage, id: String, sdf: Bool = false, contentInsets: UIEdgeInsets = .zero) throws

    Parameters

    image

    Image to add.
    id

    ID of the image.
    sdf

    Option to treat whether image is SDF(signed distance field) or not. Setting this to true allows template images to be recolored. The default value is false.
    contentInsets

    The distances the edges of content are inset from the image rectangle. If present, and if the icon uses icon-text-fit, the symbol’s text will be fit inside the content box.

  • Removes an image from the style.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func removeImage(withId id: String) throws

    Parameters

    id

    ID of the image to remove.

  • Checks whether an image exists.

    Declaration

    Swift

    public func imageExists(withId id: String) -> Bool

    Parameters

    id

    The identifier of the image.

    Return Value

    true if the given image exists, false otherwise.

  • Get an image from the style.

    Declaration

    Swift

    public func image(withId id: String) -> UIImage?

    Parameters

    id

    ID of the image.

    Return Value

    UIImage representing the data associated with the given ID, or nil if no image is associated with that ID.

Light

  • Sets a light on the style.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setLight(_ light: Light) throws

    Parameters

    light

    The Light that should be applied.

  • Sets the style global light source properties.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/#light

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setLight(properties: [String : Any]) throws

    Parameters

    properties

    A dictionary of style light properties values, with their names as key.

  • Sets a value to the style light property.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setLightProperty(_ property: String, value: Any) throws

    Parameters

    property

    Style light property name.
    value

    Style light property value.

  • Gets the value of a style light property.

    Declaration

    Swift

    public func lightProperty(_ property: String) -> Any

    Parameters

    property

    Style light property name.

    Return Value

    Style light property value.

  • Gets the value of a style light property.

    Declaration

    Swift

    public func lightProperty(_ property: String) -> StylePropertyValue

    Parameters

    property

    Style light property name.

    Return Value

    Style light property value.

Terrain

  • Sets a terrain on the style

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setTerrain(_ terrain: Terrain) throws

    Parameters

    terrain

    The Terrain that should be rendered

  • Removes terrain from style if it was set.

    Declaration

    Swift

    public func removeTerrain()

  • Sets the style global terrain source properties.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/#terrain

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setTerrain(properties: [String : Any]) throws

    Parameters

    properties

    A dictionary of style terrain properties values, with their names as key.

  • Sets a value to the named style terrain property.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setTerrainProperty(_ property: String, value: Any) throws

    Parameters

    property

    Style terrain property name.
    value

    Style terrain property value.

  • Gets the value of a style terrain property.

    Declaration

    Swift

    public func terrainProperty(_ property: String) -> Any

    Parameters

    property

    Style terrain property name.

    Return Value

    Style terrain property value.

  • Gets the value of a style terrain property.

    Declaration

    Swift

    public func terrainProperty(_ property: String) -> StylePropertyValue

    Parameters

    property

    Style terrain property name.

    Return Value

    Style terrain property value.

Atmosphere

  • Set the atmosphere of the style

    Declaration

    Swift

    public func setAtmosphere(_ atmosphere: Atmosphere) throws

    Parameters

    atmosphere

    Atmosphere object describing the fog, space and stars.

  • Remove the atmosphere of the style. No fog, space or stars would be rendered.

    Declaration

    Swift

    public func removeAtmosphere() throws

  • Set an explicit atmosphere properties

    See

    See Also style-spec/fog

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setAtmosphere(properties: [String : Any]) throws

    Parameters

    properties

    A dictionary of style fog (aka atmosphere) properties values, with their names as key.

  • Sets the value of a style atmosphere property.

    See

    See Also style-spec/fog

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setAtmosphereProperty(_ property: String, value: Any) throws

    Parameters

    property

    Style atmosphere property name.

  • Gets the value of a style atmosphere property.

    See

    See Also: https://docs.mapbox.com/mapbox-gl-js/style-spec/fog/

    Declaration

    Swift

    public func atmosphereProperty(_ property: String) -> StylePropertyValue

    Parameters

    property

    Style atmosphere property name.

    Return Value

    Style atmosphere property value.

Custom geometry

  • Adds a custom geometry to be used in the style.

    To add the data, implement the fetchTileFunction callback in the options and call setCustomGeometrySourceTileData.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func addCustomGeometrySource(withId id: String, options: CustomGeometrySourceOptions) throws

    Parameters

    id

    Style source identifier
    options

    Settings for the custom geometry

  • Set tile data of a custom geometry.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func setCustomGeometrySourceTileData(forSourceId sourceId: String, tileId: CanonicalTileID, features: [Feature]) throws

    Parameters

    sourceId

    Style source identifier
    tileId

    Identifier of the tile
    features

    An array of features to add

  • Invalidate tile for provided custom geometry source.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func invalidateCustomGeometrySourceTile(forSourceId sourceId: String, tileId: CanonicalTileID) throws

    Parameters

    sourceId

    Style source identifier
    tileId

    Identifier of the tile

  • Invalidate region for provided custom geometry source.

    Throws

    An error describing why the operation was unsuccessful.

    Declaration

    Swift

    public func invalidateCustomGeometrySourceRegion(forSourceId sourceId: String, bounds: CoordinateBounds) throws

    Parameters

    sourceId

    Style source identifier
    bounds

    Coordinate bounds.

  • This function creates an expression that will localize the textField property of a SymbolLayer

    Declaration

    Swift

    public func localizeLabels(into locale: Locale, forLayerIds layerIds: [String]? = nil) throws

    Parameters

    locale

    TheLocale to update the map to
    layerIds

    An optional list of ids that need to be localized. If nil is provided, all layers will be updated

StyleProjection