# Style Layers

- `MGLStyleLayer`

  `MGLStyleLayer` is an abstract base class for style layers. A style layer manages the layout and appearance of content at a specific z-index in a style. An `MGLStyle` object consists of one or more `MGLStyleLayer` objects.

  Each style layer defined by the style JSON file is represented at runtime by an `MGLStyleLayer` object, which you can use to refine the map’s appearance. You can also add and remove style layers dynamically.

  Create instances of `MGLBackgroundStyleLayer` and the concrete subclasses of `MGLForegroundStyleLayer` in order to use `MGLStyleLayer`‘s properties and methods. You do not create instances of `MGLStyleLayer` directly, and do not create your own subclasses of this class.

  Do not add `MGLStyleLayer` objects to the `style` property of a `MGLMapView` before `-mapView:didFinishLoadingStyle:` is called.

  See more

  #### Declaration

  Objective-C

      @interface MGLStyleLayer : NSObject

  Swift

      class MGLStyleLayer : NSObject

  View Source on GitHub

- `MGLForegroundStyleLayer`

  `MGLForegroundStyleLayer` is an abstract superclass for style layers whose content is defined by an `MGLSource` object.

  Create instances of `MGLRasterStyleLayer`, `MGLHillshadeStyleLayer`, and the concrete subclasses of `MGLVectorStyleLayer` in order to use `MGLForegroundStyleLayer`‘s methods. Do not create instances of `MGLForegroundStyleLayer` directly, and do not create your own subclasses of this class.

  See more

  #### Declaration

  Objective-C

      @interface MGLForegroundStyleLayer : MGLStyleLayer

  Swift

      class MGLForegroundStyleLayer : MGLStyleLayer

  View Source on GitHub

- `MGLBackgroundStyleLayer`

  An `MGLBackgroundStyleLayer` is a style layer that covers the entire map. Use a background style layer to configure a color or pattern to show below all other map content. If the style’s other layers use the Mapbox Streets source, the background style layer is responsible for drawing land, whereas the oceans and other bodies of water are drawn by `MGLFillStyleLayer` objects.

  A background style layer is typically the bottommost layer in a style, because it covers the entire map and can occlude any layers below it. You can therefore access it by getting the last item in the `MGLStyle.layers` array.

  If the background style layer is transparent or omitted from the style, any portion of the map view that does not show another style layer is transparent.

  See more

  #### Declaration

  Objective-C

      @interface MGLBackgroundStyleLayer : MGLStyleLayer

  Swift

      class MGLBackgroundStyleLayer : MGLStyleLayer

  View Source on GitHub

- `MGLRasterStyleLayer`

  An `MGLRasterStyleLayer` is a style layer that renders georeferenced raster imagery on the map, especially raster tiles.

  Use a raster style layer to configure the color parameters of raster tiles loaded by an `MGLRasterTileSource` object or raster images loaded by an `MGLImageSource` object. For example, you could use a raster style layer to render Mapbox Satellite imagery, a raster tile set uploaded to Mapbox Studio, or a raster map authored in TileMill, the classic Mapbox Editor, or Mapbox Studio Classic.

  Raster images may also be used as icons or patterns in a style layer. To register an image for use as an icon or pattern, use the `-[MGLStyle setImage:forName:]` method. To configure a point annotation’s image, use the `MGLAnnotationImage` class.

  You can access an existing raster style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new raster style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Add an image and Add raster imagery examples to learn how to add imagery with this style layer.

  ### Example

      let layer = MGLRasterStyleLayer(identifier: "clouds", source: source)
      layer.rasterOpacity = NSExpression(forConstantValue: 0.5)
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLRasterStyleLayer : MGLForegroundStyleLayer

  Swift

      class MGLRasterStyleLayer : MGLForegroundStyleLayer

  View Source on GitHub

- `MGLVectorStyleLayer`

  `MGLVectorStyleLayer` is an abstract superclass for style layers whose content is defined by an `MGLShapeSource` or `MGLVectorTileSource` object.

  Create instances of `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLFillExtrusionStyleLayer`, `MGLHeatmapStyleLayer`, `MGLLineStyleLayer`, and `MGLSymbolStyleLayer` in order to use `MGLVectorStyleLayer`‘s properties and methods. Do not create instances of `MGLVectorStyleLayer` directly, and do not create your own subclasses of this class.

  See more

  #### Declaration

  Objective-C

      @interface MGLVectorStyleLayer : MGLForegroundStyleLayer

  Swift

      class MGLVectorStyleLayer : MGLForegroundStyleLayer

  View Source on GitHub

- `MGLCircleStyleLayer`

  An `MGLCircleStyleLayer` is a style layer that renders one or more filled circles on the map.

  Use a circle style layer to configure the visual appearance of point or point collection features. These features can come from vector tiles loaded by an `MGLVectorTileSource` object, or they can be `MGLPointAnnotation`, `MGLPointFeature`, `MGLPointCollection`, or `MGLPointCollectionFeature` instances in an `MGLShapeSource` or `MGLComputedShapeSource` object.

  A circle style layer renders circles whose radii are measured in screen units. To display circles on the map whose radii correspond to real-world distances, use many-sided regular polygons and configure their appearance using an `MGLFillStyleLayer` object.

  You can access an existing circle style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new circle style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Data-driven circles, Add multiple shapes from a single shape source, and Cluster point data examples to learn how to add circles to your map using this style layer.

  ### Example

      let layer = MGLCircleStyleLayer(identifier: "circles", source: population)
      layer.sourceLayerIdentifier = "population"
      layer.circleColor = NSExpression(forConstantValue: UIColor.green)
      layer.circleRadius = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'exponential', 1.75, %@)",
                                        [12: 2,
                                         22: 180])
      layer.circleOpacity = NSExpression(forConstantValue: 0.7)
      layer.predicate = NSPredicate(format: "%K == %@", "marital-status", "married")
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLCircleStyleLayer : MGLVectorStyleLayer

  Swift

      class MGLCircleStyleLayer : MGLVectorStyleLayer

  View Source on GitHub

- `MGLFillStyleLayer`

  An `MGLFillStyleLayer` is a style layer that renders one or more filled (and optionally stroked) polygons on the map.

  Use a fill style layer to configure the visual appearance of polygon or multipolygon features. These features can come from vector tiles loaded by an `MGLVectorTileSource` object, or they can be `MGLPolygon`, `MGLPolygonFeature`, `MGLMultiPolygon`, or `MGLMultiPolygonFeature` instances in an `MGLShapeSource` or `MGLComputedShapeSource` object.

  You can access an existing fill style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new fill style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Select a feature within a layer example to learn how to use a `TERNARY` expression to modify the `fillOpacity` of an `MGLFillStyleLayer` object. See the Add a pattern to a polygon example to learn how to use an image to add pattern to the features styled by a `MGLFillStyleLayer`.

  ### Example

      let layer = MGLFillStyleLayer(identifier: "parks", source: parks)
      layer.sourceLayerIdentifier = "parks"
      layer.fillColor = NSExpression(forConstantValue: UIColor.green)
      layer.predicate = NSPredicate(format: "type == %@", "national-park")
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLFillStyleLayer : MGLVectorStyleLayer

  Swift

      class MGLFillStyleLayer : MGLVectorStyleLayer

  View Source on GitHub

- `MGLFillExtrusionStyleLayer`

  An `MGLFillExtrusionStyleLayer` is a style layer that renders one or more 3D extruded polygons on the map.

  Use a fill-extrusion style layer to configure the visual appearance of polygon or multipolygon features. These features can come from vector tiles loaded by an `MGLVectorTileSource` object, or they can be `MGLPolygon`, `MGLPolygonFeature`, `MGLMultiPolygon`, or `MGLMultiPolygonFeature` instances in an `MGLShapeSource` or `MGLComputedShapeSource` object.

  You can access an existing fill-extrusion style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new fill-extrusion style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Display 3D buildings example to learn how to add and style 3D layers on a map.

  ### Example

      let layer = MGLFillExtrusionStyleLayer(identifier: "buildings", source: buildings)
      layer.sourceLayerIdentifier = "building"
      layer.fillExtrusionHeight = NSExpression(forKeyPath: "height")
      layer.fillExtrusionBase = NSExpression(forKeyPath: "min_height")
      layer.predicate = NSPredicate(format: "extrude == 'true'")
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLFillExtrusionStyleLayer : MGLVectorStyleLayer

  Swift

      class MGLFillExtrusionStyleLayer : MGLVectorStyleLayer

  View Source on GitHub

- `MGLHeatmapStyleLayer`

  An `MGLHeatmapStyleLayer` is a style layer that renders a heatmap.

  A heatmap visualizes the spatial distribution of a large, dense set of point data, using color to avoid cluttering the map with individual points at low zoom levels. The points are weighted by an attribute you specify. Use a heatmap style layer in conjunction with point or point collection features. These features can come from vector tiles loaded by an `MGLVectorTileSource` object, or they can be `MGLPointAnnotation`, `MGLPointFeature`, `MGLPointCollection`, or `MGLPointCollectionFeature` instances in an `MGLShapeSource` or `MGLComputedShapeSource` object.

  Consider accompanying a heatmap style layer with an `MGLCircleStyleLayer` or `MGLSymbolStyleLayer` at high zoom levels. If you are unsure whether the point data in an `MGLShapeSource` is dense enough to warrant a heatmap, you can alternatively cluster the source using the `MGLShapeSourceOptionClustered` option and render the data using an `MGLCircleStyleLayer` or `MGLSymbolStyleLayer`.

  You can access an existing heatmap style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new heatmap style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Create a heatmap layer example to learn how to add this style layer to your map.

  ### Example

      let layer = MGLHeatmapStyleLayer(identifier: "earthquake-heat", source: earthquakes)
      layer.heatmapWeight = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:(magnitude, 'linear', nil, %@)",
                                         [0: 0,
                                          6: 1])
      layer.heatmapIntensity = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'linear', nil, %@)",
                                            [0: 1,
                                             9: 3])
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLHeatmapStyleLayer : MGLVectorStyleLayer

  Swift

      class MGLHeatmapStyleLayer : MGLVectorStyleLayer

  View Source on GitHub

- `MGLHillshadeStyleLayer`

  An `MGLHillshadeStyleLayer` is a style layer that renders raster digital elevation model (DEM) tiles on the map.

  Use a hillshade style layer to configure the color parameters of raster tiles loaded by an `MGLRasterDEMSource` object. For example, you could use a hillshade style layer to render Mapbox Terrain-RGB data.

  To display posterized hillshading based on vector shapes, as with the Mapbox Terrain source, use an `MGLVectorTileSource` object in conjunction with several `MGLFillStyleLayer` objects.

  You can access an existing hillshade style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new hillshade style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  ### Example

      let layer = MGLHillshadeStyleLayer(identifier: "hills", source: source)
      layer.hillshadeExaggeration = NSExpression(forConstantValue: 0.6)
      if let canalShadowLayer = mapView.style?.layer(withIdentifier: "waterway-river-canal-shadow") {
          mapView.style?.insertLayer(layer, below: canalShadowLayer)
      }

  See more

  #### Declaration

  Objective-C

      @interface MGLHillshadeStyleLayer : MGLForegroundStyleLayer

  Swift

      class MGLHillshadeStyleLayer : MGLForegroundStyleLayer

  View Source on GitHub

- `MGLLineStyleLayer`

  An `MGLLineStyleLayer` is a style layer that renders one or more stroked polylines on the map.

  Use a line style layer to configure the visual appearance of polyline or multipolyline features. These features can come from vector tiles loaded by an `MGLVectorTileSource` object, or they can be `MGLPolyline`, `MGLPolylineFeature`, `MGLMultiPolyline`, or `MGLMultiPolylineFeature` instances in an `MGLShapeSource` or `MGLComputedShapeSource` object.

  You can access an existing line style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new line style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Add multiple shapes from a single shape source example to learn how to add a line to your map using this style layer. See the Add a line style layer from GeoJSON example to learn how to add and style line data to an `MGLMapView` object at runtime.

  ### Example

      let layer = MGLLineStyleLayer(identifier: "trails-path", source: trails)
      layer.sourceLayerIdentifier = "trails"
      layer.lineWidth = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'exponential', 1.5, %@)",
                                     [14: 2,
                                      18: 20])
      layer.lineColor = NSExpression(forConstantValue: UIColor.brown)
      layer.lineCap = NSExpression(forConstantValue: "round")
      layer.predicate = NSPredicate(format: "%K == %@", "trail-type", "mountain-biking")
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLLineStyleLayer : MGLVectorStyleLayer

  Swift

      class MGLLineStyleLayer : MGLVectorStyleLayer

  View Source on GitHub

- `MGLSymbolStyleLayer`

  An `MGLSymbolStyleLayer` is a style layer that renders icon and text labels at points or along lines on the map.

  Use a symbol style layer to configure the visual appearance of feature labels. These features can come from vector tiles loaded by an `MGLVectorTileSource` object, or they can be `MGLShape` or `MGLFeature` instances in an `MGLShapeSource` or `MGLComputedShapeSource` object.

  You can access an existing symbol style layer using the `-[MGLStyle layerWithIdentifier:]` method if you know its identifier; otherwise, find it using the `MGLStyle.layers` property. You can also create a new symbol style layer and add it to the style using a method such as `-[MGLStyle addLayer:]`.

  #### Related examples

  See the Dynamically style interactive points and Use images to cluster point data examples learn how to style data on your map using this layer.

  ### Example

      let layer = MGLSymbolStyleLayer(identifier: "coffeeshops", source: pois)
      layer.sourceLayerIdentifier = "pois"
      layer.iconImageName = NSExpression(forConstantValue: "coffee")
      layer.iconScale = NSExpression(forConstantValue: 0.5)
      layer.text = NSExpression(forKeyPath: "name")
      layer.textTranslation = NSExpression(forConstantValue: NSValue(cgVector: CGVector(dx: 10, dy: 0)))
      layer.textJustification = NSExpression(forConstantValue: "left")
      layer.textAnchor = NSExpression(forConstantValue: "left")
      layer.predicate = NSPredicate(format: "%K == %@", "venue-type", "coffee")
      mapView.style?.addLayer(layer)

  See more

  #### Declaration

  Objective-C

      @interface MGLSymbolStyleLayer : MGLVectorStyleLayer

  Swift

      class MGLSymbolStyleLayer : MGLVectorStyleLayer

  View Source on GitHub