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.

Note: Style should only be used from the main thread.

  • Undocumented

    Declaration

    Swift

    public private(set) weak var styleManager: StyleManager! { get }

Layers

  • Adds a layer to the map

    Throws

    StyleError or type conversion errors

    Declaration

    Swift

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

    Parameters

    layer

    The layer to apply on the map
    layerPosition

    Position at which to add the map.

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

    Throws

    StyleError or type conversion errors

    Declaration

    Swift

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

    Parameters

    layer

    The layer to apply on the map
    layerPosition

    Position at which to add the map.

  • 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

    The new position to move the layer to

  • Gets a layer from the map

    Throws

    StyleError or type conversion errors

    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

    StyleError or type conversion errors

    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 or type conversion errors

    Declaration

    Swift

    public func addSource(_ source: Source, id: String) throws

    Parameters

    source

    The source to add to the map.
    identifier

    A unique source identifier.

  • Retrieves a source from the map

    Throws

    StyleError or type conversion errors

    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

    Type conversion errors.

    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 or type conversion errors

    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) 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.

  • 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.

    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 options, if any, falling back to an immediate transition otherwise.

    The style transition is re-evaluated when a new style is loaded.

    Attention

    Overridden transition options are reset once a new style has been loaded.

    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

    If not empty, the new layer will be positioned according to LayerPosition parameters.

  • 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

    If not empty, the new layer will be positioned according to LayerPosition parameters.

  • 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

    If not empty, the new layer will be positioned according to LayerPosition parameters.

  • 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

    If not empty, the new layer will be positioned according to LayerPosition parameters.

  • 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

    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.

    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.

  • 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.

  • 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 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.

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