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

#### Related examples

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

- `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 (readonly, nonatomic, class) NSURL *_Nonnull streetsStyleURL;

  Swift

      class var streetsStyleURL: URL { get }

  View Source on GitHub
- `+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.

  View Source on GitHub
- `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 (readonly, nonatomic, class) NSURL *_Nonnull outdoorsStyleURL;

  Swift

      class var outdoorsStyleURL: URL { get }

  View Source on GitHub
- `+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.

  View Source on GitHub
- `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 (readonly, nonatomic, class) NSURL *_Nonnull lightStyleURL;

  Swift

      class var lightStyleURL: URL { get }

  View Source on GitHub
- `+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.

  View Source on GitHub
- `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 (readonly, nonatomic, class) NSURL *_Nonnull darkStyleURL;

  Swift

      class var darkStyleURL: URL { get }

  View Source on GitHub
- `+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.

  View Source on GitHub
- `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

  See the Satellite styles example to learn how to initialize a map with the Mapbox Satellite style.

  #### Declaration

  Objective-C

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

  Swift

      class var satelliteStyleURL: URL { get }

  View Source on GitHub
- `+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.

  View Source on GitHub
- `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

  See the Satellite styles example to learn how to initialize a map with the Mapbox Satellite Streets style.

  #### Declaration

  Objective-C

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

  Swift

      class var satelliteStreetsStyleURL: URL { get }

  View Source on GitHub
- `+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.

  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 (readonly, copy, atomic, 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 (readwrite, strong, nonatomic)
          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 (assign, readwrite, 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 (assign, readwrite, 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 (readwrite, strong, nonatomic)
          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.

  #### Related examples

  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.

  #### Related examples

  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.

  #### Related examples

  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 (readwrite, strong, nonatomic) 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