MGLStyle

@interface MGLStyle : NSObject

The proxy object for the current map style.

MGLStyle provides a set of convenience methods for changing Mapbox default styles using MGLMapView.styleURL. Learn more about Mapbox default styles.

It is also possible to directly manipulate the current map style via MGLMapView.style by updating the style’s data sources or layers.

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

streetsStyleURL

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

@property (class, nonatomic, readonly) NSURL *_Nonnull streetsStyleURL;

Swift

class var streetsStyleURL: URL { get }

+streetsStyleURLWithVersion:

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.

outdoorsStyleURL

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

@property (class, nonatomic, readonly) NSURL *_Nonnull outdoorsStyleURL;

Swift

class var outdoorsStyleURL: URL { get }

+outdoorsStyleURLWithVersion:

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.

lightStyleURL

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

@property (class, nonatomic, readonly) NSURL *_Nonnull lightStyleURL;

Swift

class var lightStyleURL: URL { get }

+lightStyleURLWithVersion:

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.

darkStyleURL

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

@property (class, nonatomic, readonly) NSURL *_Nonnull darkStyleURL;

Swift

class var darkStyleURL: URL { get }

+darkStyleURLWithVersion:

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.

satelliteStyleURL

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.

Related example

Declaration

Objective-C

@property (class, nonatomic, readonly) NSURL *_Nonnull satelliteStyleURL;

Swift

class var satelliteStyleURL: URL { get }

+satelliteStyleURLWithVersion:

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.

satelliteStreetsStyleURL

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.

Related example

Declaration

Objective-C

@property (class, nonatomic, readonly) NSURL *_Nonnull satelliteStreetsStyleURL;

Swift

class var satelliteStreetsStyleURL: URL { get }

+satelliteStreetsStyleURLWithVersion:

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.

Accessing Metadata About the Style

name

The name of the style.

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

Declaration

Objective-C

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

Swift

var name: String? { get }

Managing Sources

sources

A set containing the style’s sources.

Declaration

Objective-C

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

Swift

var sources: Set<AnyHashable> { get set }

transition

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

Declaration

Objective-C

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

Swift

var transition: MGLTransition { get set }

performsPlacementTransitions

A boolean value indicating whether label placement transitions are enabled.

The default value of this property is YES.

Declaration

Objective-C

@property (nonatomic, assign, unsafe_unretained, readwrite)
BOOL performsPlacementTransitions;

Swift

var performsPlacementTransitions: Bool { get set }

-sourceWithIdentifier:

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.

-addSource:

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.

-removeSource:

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.

-removeSource:error:

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

- (BOOL)removeSource:(nonnull MGLSource *)source
           error:(NSError *_Nullable *_Nullable)outError;

Swift

func removeSource(_ source: MGLSource, error: ()) throws

Parameters

source

The source to remove from the current style.

outError

Upon return, if an error has occurred, a pointer to an NSError object describing the error. Pass in NULL to ignore any error.

Return Value

YES if source was removed successfully. If NO, outError contains an NSError object describing the problem.

Managing Style Layers

layers

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

Declaration

Objective-C

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

Swift

var layers: [MGLStyleLayer] { get set }

-layerWithIdentifier:

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.

-addLayer:

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.

-insertLayer:atIndex:

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.

-insertLayer:belowLayer:

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.

-insertLayer:aboveLayer:

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.

-removeLayer:

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.

Managing a Style’s Images

-imageForName:

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) -> UIImage?

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.

-setImage:forName:

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: UIImage, forName name: String)

Parameters

image

The image for the name.

name

The name of the image to set to the style.

-removeImageForName:

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.

Managing the Style’s Light

light

Provides global light source for the style.

Declaration

Objective-C

@property (nonatomic, strong, readwrite) MGLLight *_Nonnull light;

Swift

var light: MGLLight { get set }

Localizing Map Content

-localizeLabelsIntoLocale:

Attempts to localize labels in the style into the given locale.

This method automatically modifies the text property of any symbol style layer in the style 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

- (void)localizeLabelsIntoLocale:(nullable NSLocale *)locale;

Swift

func localizeLabels(into locale: Locale?)

Parameters

locale

The locale into which labels should be localized. To use the system’s preferred language, if supported, specify nil. To use the local language, specify a locale with the identifier mul.