Work with layers
Add and update layers
You can use the Maps SDK to add more styled data to the map at runtime. There are two key concepts to understand when preparing to add a layer to a style at runtime: layers and sources. Sources contain geographic data. They determine the shape of the features you’re adding to the map and where in the world they belong. Layers contain styling information. They determine how the data in a source should look on the map.
For Mapbox Standard and Mapbox Standard Satellite, you only have access to the layers that you add to the style yourself. To manipulate the Standard basemap, see the Configure a Style section.
A layer is a styled representation of data of a single type (for example polygons, lines, or points) that make up a map style. For example, roads, city labels, and rivers would be three separate layers in a map. There are several layer types (for example fill, line, and symbol). You can read more about layers in the Mapbox Style Specification.
Most layers also require a source. The source provides map data that the Maps SDK can use with a style document to render a visual representation of that data. There are several source types (for example vector tilesets, GeoJSON, and raster data). You can read more about sources in the Mapbox Style Specification.
In the Maps SDK, the style class exposes the entry point for all methods related to the style object including sources and layers.
Rendering order
Typically, layers are displayed in the order of their declaration, with later layers appearing on top of earlier ones as rendered by the SDK. When using the Mapbox Standard or Mapbox Standard Satellite, the display order primarily depends on the layer's slot, while the relative order determines their arrangement within the slot. Layers not associated with slots appear above the entire map, also maintaining their relative order.
If the Globe projection or Terrain is active, the SDK optimizes performance by batching multiple layers together, which may cause layer rearrangements. Layers draped over the globe and terrain, including fill, line, background, hillshade, and raster, are rendered below symbols, regardless of slot placement or the absence of a designated slot.
This means that layers placed with methods such as addLayerAt() might not appear at the expected position for some layer types. If your layer is not positioned in the expected place, try disabling terrain and changing the projection to Mercator.
Add a layer at runtime
To add a new layer to the map at runtime, start by adding a source using style’s addSource() method. It is important that you add the source for a new layer before attempting to add the layer itself because the source is a required parameter for most layer types.
Then, you’ll use the addLayer() method to add the layer to the style. When adding the style layer, you will specify:
- A unique ID that you assign to the new layer
- The layer type (for example fill, line, or symbol)
- What data to use by referencing a source
- The appearance of the data by setting various properties (for example color, opacity, and language)
The sample code below illustrates how to add a GeoJSON source and then add and style a line layer that uses the data in that source.
// Make the GeoJSON source with a unique string as the source ID ("line")
// and reference the location of source data
var source = GeoJsonSource(id: "line", data: data);
// Add the source to the map
mapboxMap.style.addSource(source);
// Make the line layer
// Specify a unique string as the layer ID (LAYER_ID)
// and reference the source ID ("line") added above.
let lineLayer = LineLayer(
id: "line-layer",
sourceId: "line",
lineBorderColor: Colors.black.value,
);
// Add the line layer to the map
mapboxMap.style.addLayer(lineLayer);
The exact available properties available when adding a source and layer varies by source type and layer type.
Specify order of a layer at runtime for Mapbox Standard and Mapbox Satellite Standard
Mapbox Standard and Mapbox Standard Satellite use slots to specify where custom data layers can be added. Slots are predefined locations in the Standard basemap where your layer can be inserted. To add custom layers in the appropriate location in the Standard basemap layer stack, Standard offers 3 carefully designed slots that you can leverage to place your layer. These slots will stay stable, and you can be sure that your own map won't break even as the basemap updates over time.
| Slot | Description |
|---|---|
bottom | Above polygons (land, landuse, water, etc.) |
middle | Above lines (roads, etc.) and behind 3D buildings |
top | Above POI labels and behind Place and Transit labels. Designed to be used with the symbol layers |
| not specified | Above all existing layers in the style |
Here’s an example of how to assign a slot to a layer:
var layer = LineLayer(id: "line-layer", source: "line-source", slot: "middle");
mapboxMap.style.addLayer(layer);
Make sure to use slots instead of layer ids when inserting a custom layer into the Standard basemap. If you want to order custom layers relative to each other, you can use the layer position in addLayerAt() method.
Specify order of a layer at runtime for other styles
Map styles contain many individual layers (for example roads, buildings, labels, and more). By default, when you add a new layer to the style, it is placed on top of all the other layers. You can specify where the new layer is positioned relative to existing layers when adding a layer by:
- populating the
layerPositionargument in theaddLayerAt()method to position the layer relative to its siblings
mapboxMap.style.addLayerAt(populationLayer, LayerPosition(below: "country-label"));
Remove a layer at runtime
You can remove a layer from a style using Style's removeLayer(withId:).
// Where LAYER_ID is the layer ID for an existing layer
mapboxMap.style.removeStyleLayer("LAYER_ID");