MGLStyle

 

@interface MGLStyle : NSObject

An MGLStyle object represents the active map style of an MGLMapView. A style defines both the map’s content and every aspect of its appearance. Styles can be designed in Mapbox Studio and hosted on mapbox.com. MGLStyle provides methods for inspecting and manipulating a style dynamically, with classes and properties that parallel the style JSON format defined by the Mapbox Style Specification.

You set a map view’s active style using the MGLMapView.styleURL property. MGLStyle provides a set of convenience methods that return the URLs of popular Mapbox-designed styles. Once the -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:] method is called, signaling that the style has finished loading, you can use the MGLMapView.style property to obtain the map view’s MGLStyle.

A style primarily consists of the following components:

  • Content sources supply content to be shown on the map. Use methods such as -sourceWithIdentifier: and -addSource: to configure the style’s content sources, which are represented by MGLSource objects.
  • Style layers manage the layout and appearance of content at specific z-indices in the style. Most kinds of style layers display content provided by a content source. Use methods such as -layerWithIdentifier: and -addLayer: to configure the style’s layers, which are represented by MGLStyleLayer objects.
  • Style images are used as icons and patterns in style layers. Use the -setImage:forName: method to register an image as a style image. (Annotations are represented by annotation images rather than style images. To configure an annotation’s appearance, use the -[MGLMapViewDelegate mapView:imageForAnnotation:] method.)
  • The style’s light is the light source affecting any 3D extruded fills. Use the light property to configure the style’s light, which is represented by an MGLLight object.

The MGLStyle, MGLSource, MGLStyleLayer, and MGLLight classes are collectively known as the runtime styling API. The active style influences a related API, visible feature querying, which is available through methods such as -[MGLMapView visibleFeaturesInRect:].

Some terminology differs between the Mapbox Style Specification and the various classes associated with MGLStyle. Consult the “Information for Style Authors” guide for an overview of these differences.

Note

Wait until the map style has finished loading before modifying a map’s style via any of the MGLStyle instance methods below. You can use the -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:] methods as indicators that it’s safe to modify the map’s style.

Accessing Default Styles

  • Returns the URL to the current version of the Mapbox Streets style as of publication.

    Streets is a general-purpose style with detailed road and transit networks.

    MGLMapView and MGLTilePyramidOfflineRegion use Mapbox Streets when no style is specified explicitly.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -streetsStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    + (nonnull NSURL *)streetsStyleURL;

    Swift

    class func streetsStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Streets style.

    Streets is a general-purpose style with detailed road and transit networks.

    MGLMapView and MGLTilePyramidOfflineRegion use Mapbox Streets when no style is specified explicitly.

    Declaration

    Objective-C

    + (nonnull NSURL *)streetsStyleURLWithVersion:(NSInteger)version;

    Swift

    class func streetsStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to version 8 of the Mapbox Emerald style.

    Emerald is a tactile style with subtle textures and dramatic hillshading.

    Declaration

    Objective-C

    + (nonnull NSURL *)emeraldStyleURL;

    Swift

    class func emeraldStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the current version of the Mapbox Outdoors style as of publication.

    Outdoors is a general-purpose style tailored to outdoor activities.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -outdoorsStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    + (nonnull NSURL *)outdoorsStyleURL;

    Swift

    class func outdoorsStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Outdoors style.

    Outdoors is a general-purpose style tailored to outdoor activities.

    Declaration

    Objective-C

    + (nonnull NSURL *)outdoorsStyleURLWithVersion:(NSInteger)version;

    Swift

    class func outdoorsStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to the current version of the Mapbox Light style.

    Light is a subtle, light-colored backdrop for data visualizations.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -lightStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    + (nonnull NSURL *)lightStyleURL;

    Swift

    class func lightStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Light style as of publication.

    Light is a subtle, light-colored backdrop for data visualizations.

    Declaration

    Objective-C

    + (nonnull NSURL *)lightStyleURLWithVersion:(NSInteger)version;

    Swift

    class func lightStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to the current version of the Mapbox Dark style.

    Dark is a subtle, dark-colored backdrop for data visualizations.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -darkStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    + (nonnull NSURL *)darkStyleURL;

    Swift

    class func darkStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Dark style as of publication.

    Dark is a subtle, dark-colored backdrop for data visualizations.

    Declaration

    Objective-C

    + (nonnull NSURL *)darkStyleURLWithVersion:(NSInteger)version;

    Swift

    class func darkStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to the current version of the Mapbox Satellite style.

    Satellite is high-resolution satellite and aerial imagery.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the raster tile sets included in the style – use the -satelliteStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    + (nonnull NSURL *)satelliteStyleURL;

    Swift

    class func satelliteStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Satellite style as of publication.

    Satellite is high-resolution satellite and aerial imagery.

    Declaration

    Objective-C

    + (nonnull NSURL *)satelliteStyleURLWithVersion:(NSInteger)version;

    Swift

    class func satelliteStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to version 8 of the Mapbox Satellite Streets style.

    Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets.

    Declaration

    Objective-C

    + (nonnull NSURL *)hybridStyleURL;

    Swift

    class func hybridStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the current version of the Mapbox Satellite Streets style as of publication.

    Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -satelliteStreetsStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    + (nonnull NSURL *)satelliteStreetsStyleURL;

    Swift

    class func satelliteStreetsStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Satellite Streets style.

    Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets.

    Declaration

    Objective-C

    + (nonnull NSURL *)satelliteStreetsStyleURLWithVersion:(NSInteger)version;

    Swift

    class func satelliteStreetsStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to version 2 of the Mapbox Traffic Day style.

    Declaration

    Objective-C

    + (nonnull NSURL *)trafficDayStyleURL;

    Swift

    class func trafficDayStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to the given version of the Mapbox Traffic Day style as of publication.

    Declaration

    Objective-C

    + (nonnull NSURL *)trafficDayStyleURLWithVersion:(NSInteger)version;

    Swift

    class func trafficDayStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

  • Returns the URL to the version 2 of the Mapbox Traffic Night style.

    Declaration

    Objective-C

    + (nonnull NSURL *)trafficNightStyleURL;

    Swift

    class func trafficNightStyleURL() -> URL
    View Source on GitHub

  • Returns the URL to to the version 2 of the Mapbox Traffic Night style as of publication.

    Declaration

    Objective-C

    + (nonnull NSURL *)trafficNightStyleURLWithVersion:(NSInteger)version;

    Swift

    class func trafficNightStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.
    View Source on GitHub

Accessing Metadata About the Style

  • The name of the style.

    You can customize the style’s name in Mapbox Studio.

    Declaration

    Objective-C

    @property (readonly, copy, atomic, nullable) NSString *name;

    Swift

    var name: String? { get }
    View Source on GitHub

Managing Sources

  • A set containing the style’s sources.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    NSSet<__kindof MGLSource *> *_Nonnull sources;

    Swift

    var sources: Set
    View Source on GitHub

  • Values describing animated transitions to changes on a style’s individual paint properties.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) MGLTransition transition;

    Swift

    var transition: MGLTransition { get set }
    View Source on GitHub

  • Returns a source with the given identifier in the current style.

    Note

    Source identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids source identifer name changes that will occur in the default style’s sources over time.

    Declaration

    Objective-C

    - (nullable MGLSource *)sourceWithIdentifier:(nonnull NSString *)identifier;

    Swift

    func source(withIdentifier identifier: String) -> MGLSource?

    Return Value

    An instance of a concrete subclass of MGLSource associated with the given identifier, or nil if the current style contains no such source.

    View Source on GitHub

  • Adds a new source to the current style.

    Note

    Adding the same source instance more than once will result in a MGLRedundantSourceException. Reusing the same source identifier, even with different source instances, will result in a MGLRedundantSourceIdentifierException.

    Note

    Sources should be added in -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:] to ensure that the map has loaded the style and is ready to accept a new source.

    Declaration

    Objective-C

    - (void)addSource:(nonnull MGLSource *)source;

    Swift

    func addSource(_ source: MGLSource)

    Parameters

    source

    The source to add to the current style.
    View Source on GitHub

  • Removes a source from the current style.

    Note

    Source identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids source identifer name changes that will occur in the default style’s sources over time.

    Declaration

    Objective-C

    - (void)removeSource:(nonnull MGLSource *)source;

    Swift

    func removeSource(_ source: MGLSource)

    Parameters

    source

    The source to remove from the current style.
    View Source on GitHub

Managing Style Layers

  • The layers included in the style, arranged according to their back-to-front ordering on the screen.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    NSArray<__kindof MGLStyleLayer *> *_Nonnull layers;

    Swift

    var layers: [MGLStyleLayer] { get set }
    View Source on GitHub

  • Returns a style layer with the given identifier in the current style.

    Note

    Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.

    Declaration

    Objective-C

    - (nullable MGLStyleLayer *)layerWithIdentifier:(nonnull NSString *)identifier;

    Swift

    func layer(withIdentifier identifier: String) -> MGLStyleLayer?

    Return Value

    An instance of a concrete subclass of MGLStyleLayer associated with the given identifier, or nil if the current style contains no such style layer.

    View Source on GitHub

  • Adds a new layer on top of existing layers.

    Note

    Adding the same layer instance more than once will result in a MGLRedundantLayerException. Reusing the same layer identifer, even with different layer instances, will also result in an exception.

    Note

    Layers should be added in -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:] to ensure that the map has loaded the style and is ready to accept a new layer.

    Declaration

    Objective-C

    - (void)addLayer:(nonnull MGLStyleLayer *)layer;

    Swift

    func addLayer(_ layer: MGLStyleLayer)

    Parameters

    layer

    The layer object to add to the map view. This object must be an instance of a concrete subclass of MGLStyleLayer.
    View Source on GitHub

  • Inserts a new layer into the style at the given index.

    Note

    Adding the same layer instance more than once will result in a MGLRedundantLayerException. Reusing the same layer identifer, even with different layer instances, will also result in an exception.

    Note

    Layers should be added in -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:] to ensure that the map has loaded the style and is ready to accept a new layer.

    Declaration

    Objective-C

    - (void)insertLayer:(nonnull MGLStyleLayer *)layer atIndex:(NSUInteger)index;

    Swift

    func insertLayer(_ layer: MGLStyleLayer, at index: UInt)

    Parameters

    layer

    The layer to insert.
    index

    The index at which to insert the layer. An index of 0 would send the layer to the back; an index equal to the number of objects in the layers property would bring the layer to the front.
    View Source on GitHub

  • Inserts a new layer below another layer.

    Note

    Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.

    Inserting the same layer instance more than once will result in a MGLRedundantLayerException. Reusing the same layer identifer, even with different layer instances, will also result in an exception.

    Declaration

    Objective-C

    - (void)insertLayer:(nonnull MGLStyleLayer *)layer
         belowLayer:(nonnull MGLStyleLayer *)sibling;

    Swift

    func insertLayer(_ layer: MGLStyleLayer, below sibling: MGLStyleLayer)

    Parameters

    layer

    The layer to insert.
    sibling

    An existing layer in the style.
    View Source on GitHub

  • Inserts a new layer above another layer.

    Note

    Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.

    Inserting the same layer instance more than once will result in a MGLRedundantLayerException. Reusing the same layer identifer, even with different layer instances, will also result in an exception.

    Declaration

    Objective-C

    - (void)insertLayer:(nonnull MGLStyleLayer *)layer
         aboveLayer:(nonnull MGLStyleLayer *)sibling;

    Swift

    func insertLayer(_ layer: MGLStyleLayer, above sibling: MGLStyleLayer)

    Parameters

    layer

    The layer to insert.
    sibling

    An existing layer in the style.
    View Source on GitHub

  • Removes a layer from the map view.

    Note

    Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.

    Declaration

    Objective-C

    - (void)removeLayer:(nonnull MGLStyleLayer *)layer;

    Swift

    func removeLayer(_ layer: MGLStyleLayer)

    Parameters

    layer

    The layer object to remove from the map view. This object must conform to the MGLStyleLayer protocol.
    View Source on GitHub

Managing Style Classes

  • Currently active style classes, represented as an array of string identifiers.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
    NSArray<NSString *> *_Nonnull styleClasses;

    Swift

    var styleClasses: [String] { get set }
    View Source on GitHub

  • Returns a Boolean value indicating whether the style class with the given identifier is currently active.

    Declaration

    Objective-C

    - (BOOL)hasStyleClass:(nonnull NSString *)styleClass;

    Swift

    func hasStyleClass(_ styleClass: String) -> Bool

    Parameters

    styleClass

    The style class to query for.

    Return Value

    Whether the style class is currently active.

    View Source on GitHub

  • Activates the style class with the given identifier.

    Declaration

    Objective-C

    - (void)addStyleClass:(nonnull NSString *)styleClass;

    Swift

    func addClass(_ styleClass: String)

    Parameters

    styleClass

    The style class to activate.
    View Source on GitHub

  • Deactivates the style class with the given identifier.

    Note

    Style class names are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids style class name changes that will occur in the default style over time.

    Declaration

    Objective-C

    - (void)removeStyleClass:(nonnull NSString *)styleClass;

    Swift

    func removeStyleClass(_ styleClass: String)

    Parameters

    styleClass

    The style class to deactivate.
    View Source on GitHub

Managing a Style’s Images

  • Returns the image associated with the given name in the style.

    Note

    Names and their associated images are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids image name changes that will occur in the default style over time.

    Declaration

    Objective-C

    - (nullable UIImage *)imageForName:(nonnull NSString *)name;

    Swift

    func image(forName name: String) -> NSImage?

    Parameters

    name

    The name associated with the image you want to obtain.

    Return Value

    The image associated with the given name, or nil if no image is associated with that name.

    View Source on GitHub

  • Adds or overrides an image used by the style’s layers.

    To use an image in a style layer, give it a unique name using this method, then set the iconImageName property of an MGLSymbolStyleLayer object to that name.

    Declaration

    Objective-C

    - (void)setImage:(nonnull UIImage *)image forName:(nonnull NSString *)name;

    Swift

    func setImage(_ image: NSImage, forName name: String)

    Parameters

    image

    The image for the name.
    name

    The name of the image to set to the style.
    View Source on GitHub

  • Removes a name and its associated image from the style.

    Note

    Names and their associated images are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids image name changes that will occur in the default style over time.

    Declaration

    Objective-C

    - (void)removeImageForName:(nonnull NSString *)name;

    Swift

    func removeImage(forName name: String)

    Parameters

    name

    The name of the image to remove.
    View Source on GitHub

Managing the Style's Light

Localizing Map Content

  • A Boolean value that determines whether the style attempts to localize labels in the style into the system’s preferred language.

    When this property is enabled, the style automatically modifies the text property of any symbol style layer whose source is the Mapbox Streets source. On iOS, the user can set the system’s preferred language in Settings, General Settings, Language & Region. On macOS, the user can set the system’s preferred language in the Language & Region pane of System Preferences.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL localizesLabels;

    Swift

    var localizesLabels: Bool { get set }
    View Source on GitHub