Slots
slot is a layer type that allows style authors to define named insertion points in a style’s layer stack. Slots work together with imports to let you place your own layers at specific positions within an imported style, without needing to know the names or ordering of its individual layers.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
Defining slots
Slots are defined by style authors as a layer of type slot. A slot layer only acts as a placeholder and does not render anything by itself. It has the generic layer properties like id and type, but does not have any other styling properties like layout, paint, or source.
The following example shows how a style author might define slots within a style’s layer array. The slot layers act as dividers, creating insertion points between groups of rendered layers:
{
...
"layers": [
{ "id": "land", "type": "background", ... },
{ "id": "water", "type": "fill", "source": "some-source-id", ... },
{ "id": "bottom", "type": "slot" },
{ "id": "roads", "type": "line", "source": "some-source-id", ... },
{ "id": "buildings", "type": "fill", "source": "some-source-id", ... },
{ "id": "middle", "type": "slot" },
{ "id": "road-labels", "type": "symbol", "source": "some-source-id", ... },
{ "id": "place-labels", "type": "symbol", "source": "some-source-id", ... },
{ "id": "top", "type": "slot" }
]
...
}
If the above style was imported, a layer assigned to the bottom slot would render above water but below roads. A layer assigned to middle would render above buildings but below labels.
Using slots with imports
When you import a style, its layers are rendered but not directly accessible through runtime APIs. Slots let you insert your own layers at specific positions in the imported style’s layer stack using the slot property on the layer.
This is especially useful when working with a basemap. For example, you might want to add a data visualization layer below the labels so that text remains readable, or place a route line above land and water but below streets and buildings. Slots give you a stable, well-defined way to do this.
{
"imports": [
{
"id": "basemap",
"url": "mapbox://styles/mapbox/standard"
}
],
"sources": {
"my-data": {
"type": "geojson",
"data": { "type": "FeatureCollection", "features": [] }
}
},
"layers": [
{
"id": "my-data-layer",
"type": "fill",
"source": "my-data",
"slot": "middle",
"paint": {
"fill-color": "#ff0000",
"fill-opacity": 0.5
}
}
]
}
In this example, my-data-layer is inserted into the middle slot of the imported Standard style. Without the slot property, custom layers render on top of all imported layers.
Multiple layers can be assigned to the same slot. They will render in the order they appear in the layers array, all at the position defined by that slot in the imported style.
Available slots
The slot names and positions depend on the style that defines them. Any style author can define slots in their style, but the most common use case is with the Mapbox Standard basemap styles:
bottom— Below all basemap layers. Useful for background data like polygons or heatmaps that should sit beneath everything.middle— Above land, water, and terrain but below roads, buildings, and labels. A common choice for data visualization layers.top— Above all basemap layers except labels and other critical UI layers. Useful for route lines and highlighted features.
For full details, see the Standard style reference or the Standard Satellite style reference.