Add a new layer to a slot
Upgrade to Mapbox GL JS v3
This feature is available in Mapbox GL JS v3. Learn how to migrate in our migrate to v3 guide
This example uses a new slot property to add a layer to a predetermined location in the Standard style. Set the preferred slot on the Layer object before adding it to your map and your layer will be appropriately placed in the Standard style's layer stack.
| 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. Note that the top slot is designed to be used with the symbol layers |
| not specified | If there is no identifier, the new layer will be placed above all existing layers in the style |
Slots and performance-optimized layers reordering
During 3D globe and terrain rendering, GL JS aims to batch multiple layers
together for optimal performance. This process might lead to a rearrangement
of layers. Layers draped over globe and terrain, such as fill, line,
background, hillshade, and raster, are rendered first. These layers are
rendered underneath symbols, regardless of whether they are placed in the
middle or top slots or without a designated slot.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Add a new layer to a slot</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.9.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
// You can add layers to the predetermined slots within the Standard style basemap.
style: 'mapbox://styles/mapbox/standard',
center: [-74.0060152, 40.7127281],
zoom: 5,
maxZoom: 6
});
map.on('style.load', () => {
map.addSource('urban-areas', {
'type': 'geojson',
'data': 'https://docs.mapbox.com/mapbox-gl-js/assets/ne_50m_urban_areas.geojson'
});
map.addLayer({
'id': 'urban-areas-fill',
'type': 'fill',
// This property allows you to identify which `slot` in
// the Mapbox Standard your new layer should be placed in (`bottom`, `middle`, `top`).
'slot': 'middle',
'source': 'urban-areas',
'layout': {},
'paint': {
'fill-color': '#f08',
'fill-opacity': 0.4
}
});
});
</script>
</body>
</html>
This code snippet will not work as expected until you replace
YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.import React, { useEffect, useRef } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
const MapboxExample = () => {
const mapContainerRef = useRef();
const mapRef = useRef();
useEffect(() => {
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
style: 'mapbox://styles/mapbox/standard',
center: [-74.0060152, 40.7127281],
zoom: 5,
maxZoom: 6
});
mapRef.current.on('style.load', () => {
mapRef.current.addSource('urban-areas', {
type: 'geojson',
data: 'https://docs.mapbox.com/mapbox-gl-js/assets/ne_50m_urban_areas.geojson'
});
mapRef.current.addLayer({
id: 'urban-areas-fill',
type: 'fill',
slot: 'middle',
source: 'urban-areas',
layout: {},
paint: {
'fill-color': '#f08',
'fill-opacity': 0.4
}
});
});
}, []);
return <div id="map" style={{ height: '100%' }} ref={mapContainerRef} />;
};
export default MapboxExample;
This code snippet will not work as expected until you replace
YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.Was this example helpful?