Skip to main content

Configure the Basemap during Map Initialization

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

The Mapbox Standard Style exposes configuration properties that control the look and feel of the basemap, including lighting (such as dawn, day, dusk, night) and the visibility of labels such as POIs, transit, places, and roads. This example shows how to pass these options via the config property of the style object when instantiating the Map, so the map renders with the desired appearance from the first frame — no extra API calls needed.

Explore all Standard Style configuration properties

Explore all configuration options and see how they affect the map's appearance in the Standard Style Playground.

To learn more about the full set of available options, see the Mapbox Standard Style documentation.

Configuration properties can also be updated after the map has loaded. See the Configure the basemap at Runtime example to learn how to use setConfigProperty to change these values dynamically in response to user interaction.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Configure the Basemap during Map Initialization</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.25.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.25.0/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>
    const map = new mapboxgl.Map({
        // TO MAKE THE MAP APPEAR YOU MUST
        // ADD YOUR ACCESS TOKEN FROM
        // https://account.mapbox.com
        accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
        container: 'map',
        zoom: 16.2,
        pitch: 75,
        bearing: -170,
        center: [-122.395, 37.792],
        style: 'mapbox://styles/mapbox/standard', // Use the Mapbox Standard style
        config: {
            // Initial configuration for the Mapbox Standard style set above. By default, its ID is `basemap`.
            basemap: {
                // Here, we're disabling all of the 3D layers such as landmarks, trees, and 3D extrusions.
                show3dObjects: false
            }
        }
    });
</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.
Was this example helpful?