Style The Map

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.

See the Default styles example to learn how to initialize an MGLMapView object with a Mapbox default style using MGLStyle‘s class methods.

Accessing Default Styles

+predefinedStyles

Returns list of predefined styles

Declaration

Objective-C

+ (nonnull NSArray<MGLDefaultStyle *> *)predefinedStyles;

Swift

class func predefinedStyles() -> [MGLDefaultStyle]

View Source on GitHub

+defaultStyle

Returns default style

Declaration

Objective-C

+ (nonnull MGLDefaultStyle *)defaultStyle;

Swift

class func defaultStyle() -> MGLDefaultStyle

View Source on GitHub

+defaultStyleURL
Returns default style as NSURL
Declaration
Objective-C

+ (nonnull NSURL *)defaultStyleURL;
Swift

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

+predefinedStyle:

Get predefined style by name

Declaration

Objective-C

+ (nonnull MGLDefaultStyle *)predefinedStyle:(nonnull NSString *)withStyleName;

Swift

class func predefinedStyle(_ withStyleName: String) -> MGLDefaultStyle

Parameters


                                          withStyleName

style name.

View Source on GitHub

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 (copy, readonly, nullable) NSString *name;
Swift

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

Managing Sources

sources

A set containing the style’s sources.

Declaration

Objective-C

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

Swift

var sources: Set<AnyHashable> { get set }

View Source on GitHub

transition
Values describing animated transitions to changes on a style’s individual paint properties.
Declaration
Objective-C

@property (nonatomic) MGLTransition transition;
Swift

var transition: MGLTransition { get set }
View Source on GitHub
performsPlacementTransitions
A boolean value indicating whether label placement transitions are enabled.

The default value of this property is YES.
Declaration
Objective-C

@property (nonatomic) BOOL performsPlacementTransitions;
Swift

var performsPlacementTransitions: Bool { get set }
View Source on GitHub
-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.

View Source on GitHub

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

View Source on GitHub

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

View Source on GitHub

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

View Source on GitHub

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) NSArray<__kindof MGLStyleLayer *> *_Nonnull layers;
Swift

var layers: [MGLStyleLayer] { get set }
View Source on GitHub
-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.

View Source on GitHub

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

View Source on GitHub

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

View Source on GitHub

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

See the Add multiple shapes from a single shape source example to learn how to add a layer to your map below an existing layer.

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

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

See the Add an image example to learn how to add a layer to your map above an existing layer.

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

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

View Source on GitHub

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.

View Source on GitHub

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

See the Use images to cluster point data and Cluster point data examples to learn how to add images to your map using an MGLStyle object.

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.

View Source on GitHub

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

View Source on GitHub

Managing the Style's Light

light

Provides global light source for the style.

Declaration

Objective-C

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

Swift

var light: MGLLight { get set }

View Source on GitHub

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.

View Source on GitHub

MGLLight


        @interface MGLLight : NSObject

An MGLLight object represents the light source for extruded geometries in MGLStyle.

Example

let light = MGLLight()
        let position = MGLSphericalPosition(radial: 5, azimuthal: 180, polar: 80)
        light.position = NSExpression(forConstantValue: NSValue(mglSphericalPosition: position))
        light.anchor = NSExpression(forConstantValue: "map")
        mapView.style?.light = light

See the Adjust light of 3D buildings to learn how to create and modify the light source for 3D geometries.

anchor
Whether extruded geometries are lit relative to the map or viewport.

The default value of this property is an expression that evaluates to viewport.

You can set this property to an expression containing any of the following:
- Constant MGLAnchor values
- Any of the following constant string values:
  
  map: The position of the light source is aligned to the rotation of the map.
  
  viewport: The position of the light source is aligned to the rotation of the viewport.
- Predefined functions, including mathematical and string operators
- Conditional expressions
- Variable assignments and references to assigned variables
- Step functions applied to the $zoomLevel variable
This property does not support applying interpolation functions to the $zoomLevel variable or applying interpolation or step functions to feature attributes.

This property corresponds to the anchor light property in the Mapbox Style Specification.
Declaration
Objective-C

@property (nonatomic) NSExpression *_Nonnull anchor;
Swift

var anchor: NSExpression { get set }
View Source on GitHub
position
Position of the MGLLight source relative to lit (extruded) geometries, in a MGLSphericalPosition struct [radial coordinate, azimuthal angle, polar angle] where radial indicates the distance from the center of the base of an object to its light, azimuthal indicates the position of the light relative to 0° (0° when MGLLight.anchor is set to MGLLightAnchorViewport corresponds to the top of the viewport, or 0° when MGLLight.anchor is set to MGLLightAnchorMap corresponds to due north, and degrees proceed clockwise), and polar indicates the height of the light (from 0°, directly above, to 180°, directly below).

The default value of this property is an expression that evaluates to an MGLSphericalPosition struct set to 1.15 radial, 210 azimuthal and 30 polar.

You can set this property to an expression containing any of the following:
- Constant MGLSphericalPosition values
- Predefined functions, including mathematical and string operators
- Conditional expressions
- Variable assignments and references to assigned variables
- Interpolation and step functions applied to the $zoomLevel variable
This property does not support applying interpolation or step functions to feature attributes.

This property corresponds to the position light property in the Mapbox Style Specification.

Related examples

See the Adjust light of 3D buildings example to learn how to create and modify the position of value of an MGLLight object for 3D geometries.
Declaration
Objective-C

@property (nonatomic) NSExpression *_Nonnull position;
Swift

var position: NSExpression { get set }
View Source on GitHub
positionTransition
The transition affecting any changes to this layer’s position property.

This property corresponds to the position property in the style JSON file format.
Declaration
Objective-C

@property (nonatomic) MGLTransition positionTransition;
Swift

var positionTransition: MGLTransition { get set }
View Source on GitHub
color
Color tint for lighting extruded geometries.

The default value of this property is an expression that evaluates to UIColor.whiteColor.

You can set this property to an expression containing any of the following:
- Constant UIColor values
- Predefined functions, including mathematical and string operators
- Conditional expressions
- Variable assignments and references to assigned variables
- Interpolation and step functions applied to the $zoomLevel variable
This property does not support applying interpolation or step functions to feature attributes.

This property corresponds to the color light property in the Mapbox Style Specification.
Declaration
Objective-C

@property (nonatomic) NSExpression *_Nonnull color;
Swift

var color: NSExpression { get set }
View Source on GitHub
colorTransition
The transition affecting any changes to this layer’s color property.

This property corresponds to the color property in the style JSON file format.
Declaration
Objective-C

@property (nonatomic) MGLTransition colorTransition;
Swift

var colorTransition: MGLTransition { get set }
View Source on GitHub
intensity
Intensity of lighting (on a scale from 0 to 1). Higher numbers will present as more extreme contrast.

The default value of this property is an expression that evaluates to the float 0.5.

You can set this property to an expression containing any of the following:
- Constant numeric values between 0 and 1 inclusive
- Predefined functions, including mathematical and string operators
- Conditional expressions
- Variable assignments and references to assigned variables
- Interpolation and step functions applied to the $zoomLevel variable
This property does not support applying interpolation or step functions to feature attributes.

This property corresponds to the intensity light property in the Mapbox Style Specification.
Declaration
Objective-C

@property (nonatomic) NSExpression *_Nonnull intensity;
Swift

var intensity: NSExpression { get set }
View Source on GitHub
intensityTransition
The transition affecting any changes to this layer’s intensity property.

This property corresponds to the intensity property in the style JSON file format.
Declaration
Objective-C

@property (nonatomic) MGLTransition intensityTransition;
Swift

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