> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/style-spec/llms.txt)

# 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](https://docs.mapbox.com/style-spec/reference/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](https://docs.mapbox.com/style-spec/reference/layers#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:

```json
{
  ...
  "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](https://docs.mapbox.com/style-spec/reference/imports/), 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.

```json
{
  "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.

![Visualization of how custom layers fit into slots](https://docs.mapbox.com/assets/ideal-img/style-spec-slots.f934aa7.480.png)

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](https://docs.mapbox.com/map-styles/reference/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](https://docs.mapbox.com/map-styles/reference/standard/#slots) or the [Standard Satellite style reference](https://docs.mapbox.com/map-styles/reference/standard-satellite/#slots).